| import sys |
| import os |
| import difflib |
| import subprocess |
| import re |
| import pydoc |
| import inspect |
| import unittest |
| import test.support |
| |
| 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' |
| __package__ = None |
| __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>__package__</strong> = None<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'" |
| |
| 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) |
| expected_html = expected_html_pattern % (mod_file, 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") |
| |
| |
| 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.assert_("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.assert_(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.assert_(expected in pydoc.render_doc(c)) |
| |
| |
| def test_main(): |
| test.support.run_unittest(PyDocDocTest, TestDescriptions) |
| |
| if __name__ == "__main__": |
| test_main() |