10 import test
.test_support
11 from contextlib
import contextmanager
12 from test
.test_support
import (
13 TESTFN
, forget
, rmtree
, EnvironmentVarGuard
, reap_children
)
15 from test
import pydoc_mod
17 expected_text_pattern
= \
20 test.pydoc_mod - This is a test module for test_pydoc
33 | Methods defined here:
36 | Wow, I have no function!
38 class B(__builtin__.object)
39 | Data descriptors defined here:
42 | dictionary for instance variables (if defined)
45 | list of weak references to the object (if defined)
47 | ----------------------------------------------------------------------
48 | Data and other attributes defined here:
54 This function solves all of the world's problems:
62 __author__ = 'Benjamin Peterson'
63 __credits__ = 'Nobody'
64 __version__ = '1.2.3.4'
76 expected_html_pattern
= \
78 <table width="100%%" cellspacing=0 cellpadding=2 border=0 summary="heading">
79 <tr bgcolor="#7799ee">
80 <td valign=bottom> <br>
81 <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
82 ><td align=right valign=bottom
83 ><font color="#ffffff" face="helvetica, arial"><a href=".">index</a><br><a href="file:%s">%s</a>%s</font></td></tr></table>
84 <p><tt>This is a test module for test_pydoc</tt></p>
86 <table width="100%%" cellspacing=0 cellpadding=2 border=0 summary="section">
87 <tr bgcolor="#ee77aa">
88 <td colspan=3 valign=bottom> <br>
89 <font color="#ffffff" face="helvetica, arial"><big><strong>Classes</strong></big></font></td></tr>
91 <tr><td bgcolor="#ee77aa"><tt> </tt></td><td> </td>
92 <td width="100%%"><dl>
93 <dt><font face="helvetica, arial"><a href="__builtin__.html#object">__builtin__.object</a>
96 <dt><font face="helvetica, arial"><a href="test.pydoc_mod.html#B">B</a>
99 <dt><font face="helvetica, arial"><a href="test.pydoc_mod.html#A">A</a>
102 <table width="100%%" cellspacing=0 cellpadding=2 border=0 summary="section">
103 <tr bgcolor="#ffc8d8">
104 <td colspan=3 valign=bottom> <br>
105 <font color="#000000" face="helvetica, arial"><a name="A">class <strong>A</strong></a></font></td></tr>
107 <tr bgcolor="#ffc8d8"><td rowspan=2><tt> </tt></td>
108 <td colspan=2><tt>Hello and goodbye<br> </tt></td></tr>
110 <td width="100%%">Methods defined here:<br>
111 <dl><dt><a name="A-__init__"><strong>__init__</strong></a>()</dt><dd><tt>Wow, I have no function!</tt></dd></dl>
113 </td></tr></table> <p>
114 <table width="100%%" cellspacing=0 cellpadding=2 border=0 summary="section">
115 <tr bgcolor="#ffc8d8">
116 <td colspan=3 valign=bottom> <br>
117 <font color="#000000" face="helvetica, arial"><a name="B">class <strong>B</strong></a>(<a href="__builtin__.html#object">__builtin__.object</a>)</font></td></tr>
119 <tr><td bgcolor="#ffc8d8"><tt> </tt></td><td> </td>
120 <td width="100%%">Data descriptors defined here:<br>
121 <dl><dt><strong>__dict__</strong></dt>
122 <dd><tt>dictionary for instance variables (if defined)</tt></dd>
124 <dl><dt><strong>__weakref__</strong></dt>
125 <dd><tt>list of weak references to the object (if defined)</tt></dd>
128 Data and other attributes defined here:<br>
129 <dl><dt><strong>NO_MEANING</strong> = 'eggs'</dl>
131 </td></tr></table></td></tr></table><p>
132 <table width="100%%" cellspacing=0 cellpadding=2 border=0 summary="section">
133 <tr bgcolor="#eeaa77">
134 <td colspan=3 valign=bottom> <br>
135 <font color="#ffffff" face="helvetica, arial"><big><strong>Functions</strong></big></font></td></tr>
137 <tr><td bgcolor="#eeaa77"><tt> </tt></td><td> </td>
138 <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>
140 lack of Python<br>
142 <dl><dt><a name="-nodoc_func"><strong>nodoc_func</strong></a>()</dt></dl>
143 </td></tr></table><p>
144 <table width="100%%" cellspacing=0 cellpadding=2 border=0 summary="section">
145 <tr bgcolor="#55aa55">
146 <td colspan=3 valign=bottom> <br>
147 <font color="#ffffff" face="helvetica, arial"><big><strong>Data</strong></big></font></td></tr>
149 <tr><td bgcolor="#55aa55"><tt> </tt></td><td> </td>
150 <td width="100%%"><strong>__author__</strong> = 'Benjamin Peterson'<br>
151 <strong>__credits__</strong> = 'Nobody'<br>
152 <strong>__version__</strong> = '1.2.3.4'</td></tr></table><p>
153 <table width="100%%" cellspacing=0 cellpadding=2 border=0 summary="section">
154 <tr bgcolor="#7799ee">
155 <td colspan=3 valign=bottom> <br>
156 <font color="#ffffff" face="helvetica, arial"><big><strong>Author</strong></big></font></td></tr>
158 <tr><td bgcolor="#7799ee"><tt> </tt></td><td> </td>
159 <td width="100%%">Benjamin Peterson</td></tr></table><p>
160 <table width="100%%" cellspacing=0 cellpadding=2 border=0 summary="section">
161 <tr bgcolor="#7799ee">
162 <td colspan=3 valign=bottom> <br>
163 <font color="#ffffff" face="helvetica, arial"><big><strong>Credits</strong></big></font></td></tr>
165 <tr><td bgcolor="#7799ee"><tt> </tt></td><td> </td>
166 <td width="100%%">Nobody</td></tr></table>
170 # output pattern for missing module
171 missing_pattern
= "no Python documentation found for '%s'"
173 # output pattern for module with bad imports
174 badimport_pattern
= "problem in %s - <type 'exceptions.ImportError'>: No module named %s"
176 def run_pydoc(module_name
, *args
):
178 Runs pydoc on the specified module. Returns the stripped
181 cmd
= [sys
.executable
, pydoc
.__file
__, " ".join(args
), module_name
]
183 output
= subprocess
.Popen(cmd
, stdout
=subprocess
.PIPE
).communicate()[0]
184 return output
.strip()
188 def get_pydoc_html(module
):
189 "Returns pydoc generated output as html"
190 doc
= pydoc
.HTMLDoc()
191 output
= doc
.docmodule(module
)
192 loc
= doc
.getdocloc(pydoc_mod
) or ""
194 loc
= "<br><a href=\"" + loc
+ "\">Module Docs</a>"
195 return output
.strip(), loc
197 def get_pydoc_text(module
):
198 "Returns pydoc generated output as text"
199 doc
= pydoc
.TextDoc()
200 loc
= doc
.getdocloc(pydoc_mod
) or ""
202 loc
= "\nMODULE DOCS\n " + loc
+ "\n"
204 output
= doc
.docmodule(module
)
206 # cleanup the extra text formatting that pydoc preforms
207 patt
= re
.compile('\b.')
208 output
= patt
.sub('', output
)
209 return output
.strip(), loc
211 def print_diffs(text1
, text2
):
212 "Prints unified diffs for two texts"
213 lines1
= text1
.splitlines(True)
214 lines2
= text2
.splitlines(True)
215 diffs
= difflib
.unified_diff(lines1
, lines2
, n
=0, fromfile
='expected',
217 print '\n' + ''.join(diffs
)
220 class PyDocDocTest(unittest
.TestCase
):
222 def test_html_doc(self
):
223 result
, doc_loc
= get_pydoc_html(pydoc_mod
)
224 mod_file
= inspect
.getabsfile(pydoc_mod
)
225 if sys
.platform
== 'win32':
227 mod_url
= nturl2path
.pathname2url(mod_file
)
230 expected_html
= expected_html_pattern
% (mod_url
, mod_file
, doc_loc
)
231 if result
!= expected_html
:
232 print_diffs(expected_html
, result
)
233 self
.fail("outputs are not equal, see diff above")
235 def test_text_doc(self
):
236 result
, doc_loc
= get_pydoc_text(pydoc_mod
)
237 expected_text
= expected_text_pattern
% \
238 (inspect
.getabsfile(pydoc_mod
), doc_loc
)
239 if result
!= expected_text
:
240 print_diffs(expected_text
, result
)
241 self
.fail("outputs are not equal, see diff above")
243 def test_not_here(self
):
244 missing_module
= "test.i_am_not_here"
245 result
= run_pydoc(missing_module
)
246 expected
= missing_pattern
% missing_module
247 self
.assertEqual(expected
, result
,
248 "documentation for missing module found")
250 def test_badimport(self
):
251 # This tests the fix for issue 5230, where if pydoc found the module
252 # but the module had an internal import error pydoc would report no doc
254 modname
= 'testmod_xyzzy'
256 ('i_am_not_here', 'i_am_not_here'),
257 ('test.i_am_not_here_either', 'i_am_not_here_either'),
258 ('test.i_am_not_here.neither_am_i', 'i_am_not_here.neither_am_i'),
259 ('i_am_not_here.{}'.format(modname
), 'i_am_not_here.{}'.format(modname
)),
260 ('test.{}'.format(modname
), modname
),
264 def newdirinpath(dir):
266 sys
.path
.insert(0, dir)
271 with
newdirinpath(TESTFN
), EnvironmentVarGuard() as env
:
272 env
['PYTHONPATH'] = TESTFN
273 fullmodname
= os
.path
.join(TESTFN
, modname
)
274 sourcefn
= fullmodname
+ os
.extsep
+ "py"
275 for importstring
, expectedinmsg
in testpairs
:
276 f
= open(sourcefn
, 'w')
277 f
.write("import {}\n".format(importstring
))
280 result
= run_pydoc(modname
)
283 expected
= badimport_pattern
% (modname
, expectedinmsg
)
284 self
.assertEqual(expected
, result
)
286 def test_input_strip(self
):
287 missing_module
= " test.i_am_not_here "
288 result
= run_pydoc(missing_module
)
289 expected
= missing_pattern
% missing_module
.strip()
290 self
.assertEqual(expected
, result
,
291 "white space was not stripped from module name "
292 "or other error output mismatch")
295 class TestDescriptions(unittest
.TestCase
):
297 def test_module(self
):
298 # Check that pydocfodder module can be described
299 from test
import pydocfodder
300 doc
= pydoc
.render_doc(pydocfodder
)
301 self
.assertTrue("pydocfodder" in doc
)
303 def test_classic_class(self
):
304 class C
: "Classic class"
306 self
.assertEqual(pydoc
.describe(C
), 'class C')
307 self
.assertEqual(pydoc
.describe(c
), 'instance of C')
308 expected
= 'instance of C in module %s' % __name__
309 self
.assertTrue(expected
in pydoc
.render_doc(c
))
311 def test_class(self
):
312 class C(object): "New-style class"
315 self
.assertEqual(pydoc
.describe(C
), 'class C')
316 self
.assertEqual(pydoc
.describe(c
), 'C')
317 expected
= 'C in module %s object' % __name__
318 self
.assertTrue(expected
in pydoc
.render_doc(c
))
322 test
.test_support
.run_unittest(PyDocDocTest
,
325 if __name__
== "__main__":