import sys import os import os.path import difflib import subprocess import re import pydoc import inspect import unittest import test.support import xml.etree 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 = \ """
 
 
test.pydoc_mod (version 1.2.3.4)
index
%s%s

This is a test module for test_pydoc

\x20\x20\x20\x20
 
Classes
       
builtins.object
A
B

\x20\x20\x20\x20
 
class A(builtins.object)
    Hello and goodbye
 
  Methods defined here:
__init__()
Wow, I have no function!

Data descriptors defined here:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

\x20\x20\x20\x20
 
class B(builtins.object)
     Data descriptors defined here:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

Data and other attributes defined here:
NO_MEANING = 'eggs'

\x20\x20\x20\x20
 
Functions
       
doc_func()
This function solves all of the world's problems:
hunger
lack of Python
war
nodoc_func()

\x20\x20\x20\x20
 
Data
        __author__ = 'Benjamin Peterson'
__credits__ = 'Nobody'
__version__ = '1.2.3.4'

\x20\x20\x20\x20
 
Author
        Benjamin Peterson

\x20\x20\x20\x20
 
Credits
        Nobody
""".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 = "
Module Docs" 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_issue8225(self): # Test issue8225 to ensure no doc link appears for xml.etree result, doc_loc = get_pydoc_text(xml.etree) self.assertEqual(doc_loc, "", "MODULE DOCS incorrectly includes a link") 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) def test_stripid(self): # test with strings, other implementations might have different repr() stripid = pydoc.stripid # strip the id self.assertEqual(stripid(''), '') self.assertEqual(stripid(''), '') # nothing to strip, return the same text self.assertEqual(stripid('42'), '42') self.assertEqual(stripid(""), "") 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()