import sys import os import os.path import difflib import subprocess import re import pydoc import inspect import unittest import xml.etree import test.test_support from contextlib import contextmanager from collections import namedtuple from test.test_support import ( TESTFN, forget, rmtree, EnvironmentVarGuard, reap_children, captured_stdout) from test import pydoc_mod expected_text_pattern = \ """ NAME test.pydoc_mod - This is a test module for test_pydoc FILE %s %s CLASSES __builtin__.object B A \x20\x20\x20\x20 class A | Hello and goodbye |\x20\x20 | Methods defined here: |\x20\x20 | __init__() | Wow, I have no function! \x20\x20\x20\x20 class B(__builtin__.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
       
__builtin__.object
B
A

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

\x20\x20\x20\x20
 
class B(__builtin__.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 - : 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] try: output = subprocess.Popen(cmd, stdout=subprocess.PIPE).communicate()[0] return output.strip() finally: reap_children() 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): @unittest.skipIf(sys.flags.optimize >= 2, "Docstrings are omitted with -O2 and above") 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") @unittest.skipIf(sys.flags.optimize >= 2, "Docstrings are omitted with -O2 and 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 = run_pydoc(missing_module) 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) 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 = run_pydoc(missing_module) expected = missing_pattern % missing_module.strip() self.assertEqual(expected, result, "white space was not stripped from module name " "or other error output mismatch") 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.assertIn("pydocfodder", doc) def test_classic_class(self): class C: "Classic class" c = C() self.assertEqual(pydoc.describe(C), 'class C') self.assertEqual(pydoc.describe(c), 'instance of C') expected = 'instance of C in module %s' % __name__ self.assertIn(expected, 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.assertIn(expected, pydoc.render_doc(c)) def test_namedtuple_public_underscore(self): NT = namedtuple('NT', ['abc', 'def'], rename=True) with captured_stdout() as help_io: help(NT) helptext = help_io.getvalue() self.assertIn('_1', helptext) self.assertIn('_replace', helptext) self.assertIn('_asdict', helptext) def test_main(): test.test_support.run_unittest(PyDocDocTest, TestDescriptions) if __name__ == "__main__": test_main()