import sys import os import os.path import difflib import subprocess import re import pydoc import inspect import unittest import test.support from contextlib import contextmanager from test.support import TESTFN, forget, rmtree, EnvironmentVarGuard from test import pydoc_mod expected_text_pattern = \ """ NAME test.pydoc_mod - This is a test module for test_pydoc FILE %s %s CLASSES builtins.object A B \x20\x20\x20\x20 class A(builtins.object) | Hello and goodbye |\x20\x20 | Methods defined here: |\x20\x20 | __init__() | Wow, I have no function! |\x20\x20 | ---------------------------------------------------------------------- | Data descriptors defined here: |\x20\x20 | __dict__ | dictionary for instance variables (if defined) |\x20\x20 | __weakref__ | list of weak references to the object (if defined) \x20\x20\x20\x20 class B(builtins.object) | Data descriptors defined here: |\x20\x20 | __dict__ | dictionary for instance variables (if defined) |\x20\x20 | __weakref__ | list of weak references to the object (if defined) |\x20\x20 | ---------------------------------------------------------------------- | Data and other attributes defined here: |\x20\x20 | NO_MEANING = 'eggs' FUNCTIONS doc_func() This function solves all of the world's problems: hunger lack of Python war \x20\x20\x20\x20 nodoc_func() DATA __author__ = 'Benjamin Peterson' __credits__ = 'Nobody' __version__ = '1.2.3.4' VERSION 1.2.3.4 AUTHOR Benjamin Peterson CREDITS Nobody """.strip() expected_html_pattern = \ """ <table width="100%%" cellspacing=0 cellpadding=2 border=0 summary="heading"> <tr bgcolor="#7799ee"> <td valign=bottom> <br> <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 ><td align=right valign=bottom ><font color="#ffffff" face="helvetica, arial"><a href=".">index</a><br><a href="file:%s">%s</a>%s</font></td></tr></table> <p><tt>This is a test module for test_pydoc</tt></p> <p> <table width="100%%" cellspacing=0 cellpadding=2 border=0 summary="section"> <tr bgcolor="#ee77aa"> <td colspan=3 valign=bottom> <br> <font color="#ffffff" face="helvetica, arial"><big><strong>Classes</strong></big></font></td></tr> \x20\x20\x20\x20 <tr><td bgcolor="#ee77aa"><tt> </tt></td><td> </td> <td width="100%%"><dl> <dt><font face="helvetica, arial"><a href="builtins.html#object">builtins.object</a> </font></dt><dd> <dl> <dt><font face="helvetica, arial"><a href="test.pydoc_mod.html#A">A</a> </font></dt><dt><font face="helvetica, arial"><a href="test.pydoc_mod.html#B">B</a> </font></dt></dl> </dd> </dl> <p> <table width="100%%" cellspacing=0 cellpadding=2 border=0 summary="section"> <tr bgcolor="#ffc8d8"> <td colspan=3 valign=bottom> <br> <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> \x20\x20\x20\x20 <tr bgcolor="#ffc8d8"><td rowspan=2><tt> </tt></td> <td colspan=2><tt>Hello and goodbye<br> </tt></td></tr> <tr><td> </td> <td width="100%%">Methods defined here:<br> <dl><dt><a name="A-__init__"><strong>__init__</strong></a>()</dt><dd><tt>Wow, I have no function!</tt></dd></dl> <hr> Data descriptors defined here:<br> <dl><dt><strong>__dict__</strong></dt> <dd><tt>dictionary for instance variables (if defined)</tt></dd> </dl> <dl><dt><strong>__weakref__</strong></dt> <dd><tt>list of weak references to the object (if defined)</tt></dd> </dl> </td></tr></table> <p> <table width="100%%" cellspacing=0 cellpadding=2 border=0 summary="section"> <tr bgcolor="#ffc8d8"> <td colspan=3 valign=bottom> <br> <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> \x20\x20\x20\x20 <tr><td bgcolor="#ffc8d8"><tt> </tt></td><td> </td> <td width="100%%">Data descriptors defined here:<br> <dl><dt><strong>__dict__</strong></dt> <dd><tt>dictionary for instance variables (if defined)</tt></dd> </dl> <dl><dt><strong>__weakref__</strong></dt> <dd><tt>list of weak references to the object (if defined)</tt></dd> </dl> <hr> Data and other attributes defined here:<br> <dl><dt><strong>NO_MEANING</strong> = 'eggs'</dl> </td></tr></table></td></tr></table><p> <table width="100%%" cellspacing=0 cellpadding=2 border=0 summary="section"> <tr bgcolor="#eeaa77"> <td colspan=3 valign=bottom> <br> <font color="#ffffff" face="helvetica, arial"><big><strong>Functions</strong></big></font></td></tr> \x20\x20\x20\x20 <tr><td bgcolor="#eeaa77"><tt> </tt></td><td> </td> <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> hunger<br> lack of Python<br> war</tt></dd></dl> <dl><dt><a name="-nodoc_func"><strong>nodoc_func</strong></a>()</dt></dl> </td></tr></table><p> <table width="100%%" cellspacing=0 cellpadding=2 border=0 summary="section"> <tr bgcolor="#55aa55"> <td colspan=3 valign=bottom> <br> <font color="#ffffff" face="helvetica, arial"><big><strong>Data</strong></big></font></td></tr> \x20\x20\x20\x20 <tr><td bgcolor="#55aa55"><tt> </tt></td><td> </td> <td width="100%%"><strong>__author__</strong> = 'Benjamin Peterson'<br> <strong>__credits__</strong> = 'Nobody'<br> <strong>__version__</strong> = '1.2.3.4'</td></tr></table><p> <table width="100%%" cellspacing=0 cellpadding=2 border=0 summary="section"> <tr bgcolor="#7799ee"> <td colspan=3 valign=bottom> <br> <font color="#ffffff" face="helvetica, arial"><big><strong>Author</strong></big></font></td></tr> \x20\x20\x20\x20 <tr><td bgcolor="#7799ee"><tt> </tt></td><td> </td> <td width="100%%">Benjamin Peterson</td></tr></table><p> <table width="100%%" cellspacing=0 cellpadding=2 border=0 summary="section"> <tr bgcolor="#7799ee"> <td colspan=3 valign=bottom> <br> <font color="#ffffff" face="helvetica, arial"><big><strong>Credits</strong></big></font></td></tr> \x20\x20\x20\x20 <tr><td bgcolor="#7799ee"><tt> </tt></td><td> </td> <td width="100%%">Nobody</td></tr></table> """.strip() # output pattern for missing module missing_pattern = "no Python documentation found for '%s'" # output pattern for module with bad imports badimport_pattern = "problem in %s - ImportError: No module named %s" def run_pydoc(module_name, *args): """ Runs pydoc on the specified module. Returns the stripped output of pydoc. """ cmd = [sys.executable, pydoc.__file__, " ".join(args), module_name] output = subprocess.Popen(cmd, stdout=subprocess.PIPE).stdout.read() return output.strip() def get_pydoc_html(module): "Returns pydoc generated output as html" doc = pydoc.HTMLDoc() output = doc.docmodule(module) loc = doc.getdocloc(pydoc_mod) or "" if loc: loc = "<br><a href=\"" + loc + "\">Module Docs</a>" return output.strip(), loc def get_pydoc_text(module): "Returns pydoc generated output as text" doc = pydoc.TextDoc() loc = doc.getdocloc(pydoc_mod) or "" if loc: loc = "\nMODULE DOCS\n " + loc + "\n" output = doc.docmodule(module) # cleanup the extra text formatting that pydoc preforms patt = re.compile('\b.') output = patt.sub('', output) return output.strip(), loc def print_diffs(text1, text2): "Prints unified diffs for two texts" lines1 = text1.splitlines(True) lines2 = text2.splitlines(True) diffs = difflib.unified_diff(lines1, lines2, n=0, fromfile='expected', tofile='got') print('\n' + ''.join(diffs)) class PyDocDocTest(unittest.TestCase): def test_html_doc(self): result, doc_loc = get_pydoc_html(pydoc_mod) mod_file = inspect.getabsfile(pydoc_mod) if sys.platform == 'win32': import nturl2path mod_url = nturl2path.pathname2url(mod_file) else: mod_url = mod_file expected_html = expected_html_pattern % (mod_url, mod_file, doc_loc) if result != expected_html: print_diffs(expected_html, result) self.fail("outputs are not equal, see diff above") def test_text_doc(self): result, doc_loc = get_pydoc_text(pydoc_mod) expected_text = expected_text_pattern % \ (inspect.getabsfile(pydoc_mod), doc_loc) if result != expected_text: print_diffs(expected_text, result) self.fail("outputs are not equal, see diff above") def test_not_here(self): missing_module = "test.i_am_not_here" result = str(run_pydoc(missing_module), 'ascii') expected = missing_pattern % missing_module self.assertEqual(expected, result, "documentation for missing module found") def test_badimport(self): # This tests the fix for issue 5230, where if pydoc found the module # but the module had an internal import error pydoc would report no doc # found. modname = 'testmod_xyzzy' testpairs = ( ('i_am_not_here', 'i_am_not_here'), ('test.i_am_not_here_either', 'i_am_not_here_either'), ('test.i_am_not_here.neither_am_i', 'i_am_not_here.neither_am_i'), ('i_am_not_here.{}'.format(modname), 'i_am_not_here.{}'.format(modname)), ('test.{}'.format(modname), modname), ) @contextmanager def newdirinpath(dir): os.mkdir(dir) sys.path.insert(0, dir) yield sys.path.pop(0) rmtree(dir) with newdirinpath(TESTFN), EnvironmentVarGuard() as env: env['PYTHONPATH'] = TESTFN fullmodname = os.path.join(TESTFN, modname) sourcefn = fullmodname + os.extsep + "py" for importstring, expectedinmsg in testpairs: f = open(sourcefn, 'w') f.write("import {}\n".format(importstring)) f.close() try: result = run_pydoc(modname).decode("ascii") finally: forget(modname) expected = badimport_pattern % (modname, expectedinmsg) self.assertEqual(expected, result) def test_input_strip(self): missing_module = " test.i_am_not_here " result = str(run_pydoc(missing_module), 'ascii') expected = missing_pattern % missing_module.strip() self.assertEqual(expected, result) class TestDescriptions(unittest.TestCase): def test_module(self): # Check that pydocfodder module can be described from test import pydocfodder doc = pydoc.render_doc(pydocfodder) self.assertTrue("pydocfodder" in doc) def test_classic_class(self): class C: "Classic class" c = C() self.assertEqual(pydoc.describe(C), 'class C') self.assertEqual(pydoc.describe(c), 'C') expected = 'C in module %s' % __name__ self.assertTrue(expected in pydoc.render_doc(c)) def test_class(self): class C(object): "New-style class" c = C() self.assertEqual(pydoc.describe(C), 'class C') self.assertEqual(pydoc.describe(c), 'C') expected = 'C in module %s object' % __name__ self.assertTrue(expected in pydoc.render_doc(c)) def test_main(): test.support.run_unittest(PyDocDocTest, TestDescriptions) if __name__ == "__main__": test_main()