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