Debian Codegraph @

Lib/test/test_pydoc/test_pydoc.py

raw
1 import datetime
2 import os
3 import sys
4 import contextlib
5 import importlib.util
6 import inspect
7 import io
8 import pydoc
9 import py_compile
10 import keyword
11 import _pickle
12 import pkgutil
13 import re
14 import tempfile
15 import test.support
16 import time
17 import types
18 import typing
19 import unittest
20 import unittest.mock
21 import urllib.parse
22 import xml.etree
23 import xml.etree.ElementTree
24 import textwrap
25 from io import StringIO
26 from collections import namedtuple
27 from urllib.request import urlopen, urlcleanup
28 from test import support
29 from test.support import import_helper
30 from test.support import os_helper
31 from test.support.script_helper import (assert_python_ok,
32 assert_python_failure, spawn_python)
33 from test.support import threading_helper
34 from test.support import (reap_children, captured_stdout,
35 captured_stderr, is_wasm32,
36 requires_docstrings, MISSING_C_DOCSTRINGS)
37 from test.support.os_helper import (TESTFN, rmtree, unlink)
38 from test.test_pydoc import pydoc_mod
39 from test.test_pydoc import pydocfodder
40
41
42 class nonascii:
43 'Це не латиниця'
44 pass
45
46 if test.support.HAVE_DOCSTRINGS:
47 expected_data_docstrings = (
48 'dictionary for instance variables',
49 'list of weak references to the object',
50 ) * 2
51 else:
52 expected_data_docstrings = ('', '', '', '')
53
54 expected_text_pattern = """
55 NAME
56 test.test_pydoc.pydoc_mod - This is a test module for test_pydoc
57 %s
58 CLASSES
59 builtins.object
60 A
61 B
62 C
63
64 class A(builtins.object)
65 | Hello and goodbye
66 |
67 | Methods defined here:
68 |
69 | __init__()
70 | Wow, I have no function!
71 |
72 | ----------------------------------------------------------------------
73 | Data descriptors defined here:
74 |
75 | __dict__%s
76 |
77 | __weakref__%s
78
79 class B(builtins.object)
80 | Data descriptors defined here:
81 |
82 | __dict__%s
83 |
84 | __weakref__%s
85 |
86 | ----------------------------------------------------------------------
87 | Data and other attributes defined here:
88 |
89 | NO_MEANING = 'eggs'
90
91 class C(builtins.object)
92 | Methods defined here:
93 |
94 | get_answer(self)
95 | Return say_no()
96 |
97 | is_it_true(self)
98 | Return self.get_answer()
99 |
100 | say_no(self)
101 |
102 | ----------------------------------------------------------------------
103 | Class methods defined here:
104 |
105 | __class_getitem__(item)
106 |
107 | ----------------------------------------------------------------------
108 | Data descriptors defined here:
109 |
110 | __dict__
111 | dictionary for instance variables
112 |
113 | __weakref__
114 | list of weak references to the object
115
116 FUNCTIONS
117 doc_func()
118 This function solves all of the world's problems:
119 hunger
120 lack of Python
121 war
122
123 nodoc_func()
124
125 DATA
126 __xyz__ = 'X, Y and Z'
127 c_alias = test.test_pydoc.pydoc_mod.C[int]
128 list_alias1 = typing.List[int]
129 list_alias2 = list[int]
130 type_union1 = int | str
131 type_union2 = int | str
132
133 VERSION
134 1.2.3.4
135
136 AUTHOR
137 Benjamin Peterson
138
139 CREDITS
140 Nobody
141
142 FILE
143 %s
144 """.strip()
145
146 expected_text_data_docstrings = tuple('\n | ' + s if s else ''
147 for s in expected_data_docstrings)
148
149 html2text_of_expected = """
150 test.test_pydoc.pydoc_mod (version 1.2.3.4)
151 This is a test module for test_pydoc
152
153 Modules
154 types
155 typing
156
157 Classes
158 builtins.object
159 A
160 B
161 C
162
163 class A(builtins.object)
164 Hello and goodbye
165
166 Methods defined here:
167 __init__()
168 Wow, I have no function!
169 ----------------------------------------------------------------------
170 Data descriptors defined here:
171 __dict__
172 dictionary for instance variables
173 __weakref__
174 list of weak references to the object
175
176 class B(builtins.object)
177 Data descriptors defined here:
178 __dict__
179 dictionary for instance variables
180 __weakref__
181 list of weak references to the object
182 ----------------------------------------------------------------------
183 Data and other attributes defined here:
184 NO_MEANING = 'eggs'
185
186
187 class C(builtins.object)
188 Methods defined here:
189 get_answer(self)
190 Return say_no()
191 is_it_true(self)
192 Return self.get_answer()
193 say_no(self)
194 ----------------------------------------------------------------------
195 Class methods defined here:
196 __class_getitem__(item)
197 ----------------------------------------------------------------------
198 Data descriptors defined here:
199 __dict__
200 dictionary for instance variables
201 __weakref__
202 list of weak references to the object
203
204 Functions
205 doc_func()
206 This function solves all of the world's problems:
207 hunger
208 lack of Python
209 war
210 nodoc_func()
211
212 Data
213 __xyz__ = 'X, Y and Z'
214 c_alias = test.test_pydoc.pydoc_mod.C[int]
215 list_alias1 = typing.List[int]
216 list_alias2 = list[int]
217 type_union1 = int | str
218 type_union2 = int | str
219
220 Author
221 Benjamin Peterson
222
223 Credits
224 Nobody
225 """
226
227 expected_html_data_docstrings = tuple(s.replace(' ', ' ')
228 for s in expected_data_docstrings)
229
230 # output pattern for missing module
231 missing_pattern = '''\
232 No Python documentation found for %r.
233 Use help() to get the interactive help utility.
234 Use help(str) for help on the str class.'''.replace('\n', os.linesep)
235
236 # output pattern for module with bad imports
237 badimport_pattern = "problem in %s - ModuleNotFoundError: No module named %r"
238
239 expected_dynamicattribute_pattern = """
240 Help on class DA in module %s:
241
242 class DA(builtins.object)
243 | Data descriptors defined here:
244 |
245 | __dict__%s
246 |
247 | __weakref__%s
248 |
249 | ham
250 |
251 | ----------------------------------------------------------------------
252 | Data and other attributes inherited from Meta:
253 |
254 | ham = 'spam'
255 """.strip()
256
257 expected_virtualattribute_pattern1 = """
258 Help on class Class in module %s:
259
260 class Class(builtins.object)
261 | Data and other attributes inherited from Meta:
262 |
263 | LIFE = 42
264 """.strip()
265
266 expected_virtualattribute_pattern2 = """
267 Help on class Class1 in module %s:
268
269 class Class1(builtins.object)
270 | Data and other attributes inherited from Meta1:
271 |
272 | one = 1
273 """.strip()
274
275 expected_virtualattribute_pattern3 = """
276 Help on class Class2 in module %s:
277
278 class Class2(Class1)
279 | Method resolution order:
280 | Class2
281 | Class1
282 | builtins.object
283 |
284 | Data and other attributes inherited from Meta1:
285 |
286 | one = 1
287 |
288 | ----------------------------------------------------------------------
289 | Data and other attributes inherited from Meta3:
290 |
291 | three = 3
292 |
293 | ----------------------------------------------------------------------
294 | Data and other attributes inherited from Meta2:
295 |
296 | two = 2
297 """.strip()
298
299 expected_missingattribute_pattern = """
300 Help on class C in module %s:
301
302 class C(builtins.object)
303 | Data and other attributes defined here:
304 |
305 | here = 'present!'
306 """.strip()
307
308 def run_pydoc(module_name, *args, **env):
309 """
310 Runs pydoc on the specified module. Returns the stripped
311 output of pydoc.
312 """
313 args = args + (module_name,)
314 # do not write bytecode files to avoid caching errors
315 rc, out, err = assert_python_ok('-B', pydoc.__file__, *args, **env)
316 return out.strip()
317
318 def run_pydoc_fail(module_name, *args, **env):
319 """
320 Runs pydoc on the specified module expecting a failure.
321 """
322 args = args + (module_name,)
323 rc, out, err = assert_python_failure('-B', pydoc.__file__, *args, **env)
324 return out.strip()
325
326 def get_pydoc_html(module):
327 "Returns pydoc generated output as html"
328 doc = pydoc.HTMLDoc()
329 output = doc.docmodule(module)
330 loc = doc.getdocloc(pydoc_mod) or ""
331 if loc:
332 loc = "<br><a href=\"" + loc + "\">Module Docs</a>"
333 return output.strip(), loc
334
335 def clean_text(doc):
336 # clean up the extra text formatting that pydoc performs
337 return re.sub('\b.', '', doc)
338
339 def get_pydoc_link(module):
340 "Returns a documentation web link of a module"
341 abspath = os.path.abspath
342 dirname = os.path.dirname
343 basedir = dirname(dirname(dirname(abspath(__file__))))
344 doc = pydoc.TextDoc()
345 loc = doc.getdocloc(module, basedir=basedir)
346 return loc
347
348 def get_pydoc_text(module):
349 "Returns pydoc generated output as text"
350 doc = pydoc.TextDoc()
351 loc = doc.getdocloc(pydoc_mod) or ""
352 if loc:
353 loc = "\nMODULE DOCS\n " + loc + "\n"
354
355 output = doc.docmodule(module)
356 output = clean_text(output)
357 return output.strip(), loc
358
359 def get_html_title(text):
360 # Bit of hack, but good enough for test purposes
361 header, _, _ = text.partition("</head>")
362 _, _, title = header.partition("<title>")
363 title, _, _ = title.partition("</title>")
364 return title
365
366
367 def html2text(html):
368 """A quick and dirty implementation of html2text.
369
370 Tailored for pydoc tests only.
371 """
372 html = html.replace("<dd>", "\n")
373 html = html.replace("<hr>", "-"*70)
374 html = re.sub("<.*?>", "", html)
375 html = pydoc.replace(html, "&nbsp;", " ", "&gt;", ">", "&lt;", "<")
376 return html
377
378
379 class PydocBaseTest(unittest.TestCase):
380 def tearDown(self):
381 # Self-testing. Mocking only works if sys.modules['pydoc'] and pydoc
382 # are the same. But some pydoc functions reload the module and change
383 # sys.modules, so check that it was restored.
384 self.assertIs(sys.modules['pydoc'], pydoc)
385
386 def _restricted_walk_packages(self, walk_packages, path=None):
387 """
388 A version of pkgutil.walk_packages() that will restrict itself to
389 a given path.
390 """
391 default_path = path or [os.path.dirname(__file__)]
392 def wrapper(path=None, prefix='', onerror=None):
393 return walk_packages(path or default_path, prefix, onerror)
394 return wrapper
395
396 @contextlib.contextmanager
397 def restrict_walk_packages(self, path=None):
398 walk_packages = pkgutil.walk_packages
399 pkgutil.walk_packages = self._restricted_walk_packages(walk_packages,
400 path)
401 try:
402 yield
403 finally:
404 pkgutil.walk_packages = walk_packages
405
406 def call_url_handler(self, url, expected_title):
407 text = pydoc._url_handler(url, "text/html")
408 result = get_html_title(text)
409 # Check the title to ensure an unexpected error page was not returned
410 self.assertEqual(result, expected_title, text)
411 return text
412
413
414 class PydocDocTest(unittest.TestCase):
415 maxDiff = None
416 def tearDown(self):
417 self.assertIs(sys.modules['pydoc'], pydoc)
418
419 @unittest.skipIf(hasattr(sys, 'gettrace') and sys.gettrace(),
420 'trace function introduces __locals__ unexpectedly')
421 @requires_docstrings
422 def test_html_doc(self):
423 result, doc_loc = get_pydoc_html(pydoc_mod)
424 text_result = html2text(result)
425 text_lines = [line.strip() for line in text_result.splitlines()]
426 text_lines = [line for line in text_lines if line]
427 del text_lines[1]
428 expected_lines = html2text_of_expected.splitlines()
429 expected_lines = [line.strip() for line in expected_lines if line]
430 self.assertEqual(text_lines, expected_lines)
431 mod_file = inspect.getabsfile(pydoc_mod)
432 mod_url = urllib.parse.quote(mod_file)
433 self.assertIn(mod_url, result)
434 self.assertIn(mod_file, result)
435 self.assertIn(doc_loc, result)
436
437 @unittest.skipIf(hasattr(sys, 'gettrace') and sys.gettrace(),
438 'trace function introduces __locals__ unexpectedly')
439 @requires_docstrings
440 def test_text_doc(self):
441 result, doc_loc = get_pydoc_text(pydoc_mod)
442 expected_text = expected_text_pattern % (
443 (doc_loc,) +
444 expected_text_data_docstrings +
445 (inspect.getabsfile(pydoc_mod),))
446 self.assertEqual(expected_text, result)
447
448 def test_text_enum_member_with_value_zero(self):
449 # Test issue #20654 to ensure enum member with value 0 can be
450 # displayed. It used to throw KeyError: 'zero'.
451 import enum
452 class BinaryInteger(enum.IntEnum):
453 zero = 0
454 one = 1
455 doc = pydoc.render_doc(BinaryInteger)
456 self.assertIn('BinaryInteger.zero', doc)
457
458 def test_slotted_dataclass_with_field_docs(self):
459 import dataclasses
460 @dataclasses.dataclass(slots=True)
461 class My:
462 x: int = dataclasses.field(doc='Docstring for x')
463 doc = pydoc.render_doc(My)
464 self.assertIn('Docstring for x', doc)
465
466 def test_mixed_case_module_names_are_lower_cased(self):
467 # issue16484
468 doc_link = get_pydoc_link(xml.etree.ElementTree)
469 self.assertIn('xml.etree.elementtree', doc_link)
470
471 def test_issue8225(self):
472 # Test issue8225 to ensure no doc link appears for xml.etree
473 result, doc_loc = get_pydoc_text(xml.etree)
474 self.assertEqual(doc_loc, "", "MODULE DOCS incorrectly includes a link")
475
476 def test_online_docs_link(self):
477 import encodings.idna
478 import importlib._bootstrap
479
480 module_docs = {
481 'encodings': 'codecs#module-encodings',
482 'encodings.idna': 'codecs#module-encodings.idna',
483 }
484
485 with unittest.mock.patch('pydoc_data.module_docs.module_docs', module_docs):
486 doc = pydoc.TextDoc()
487
488 basedir = os.path.dirname(encodings.__file__)
489 doc_link = doc.getdocloc(encodings, basedir=basedir)
490 self.assertIsNotNone(doc_link)
491 self.assertIn('codecs#module-encodings', doc_link)
492 self.assertNotIn('encodings.html', doc_link)
493
494 doc_link = doc.getdocloc(encodings.idna, basedir=basedir)
495 self.assertIsNotNone(doc_link)
496 self.assertIn('codecs#module-encodings.idna', doc_link)
497 self.assertNotIn('encodings.idna.html', doc_link)
498
499 doc_link = doc.getdocloc(importlib._bootstrap, basedir=basedir)
500 self.assertIsNone(doc_link)
501
502 def test_getpager_with_stdin_none(self):
503 previous_stdin = sys.stdin
504 try:
505 sys.stdin = None
506 pydoc.getpager() # Shouldn't fail.
507 finally:
508 sys.stdin = previous_stdin
509
510 def test_non_str_name(self):
511 # issue14638
512 # Treat illegal (non-str) name like no name
513
514 class A:
515 __name__ = 42
516 class B:
517 pass
518 adoc = pydoc.render_doc(A())
519 bdoc = pydoc.render_doc(B())
520 self.assertEqual(adoc.replace("A", "B"), bdoc)
521
522 def test_not_here(self):
523 missing_module = "test.i_am_not_here"
524 result = str(run_pydoc_fail(missing_module), 'ascii')
525 expected = missing_pattern % missing_module
526 self.assertEqual(expected, result,
527 "documentation for missing module found")
528
529 @requires_docstrings
530 def test_not_ascii(self):
531 result = run_pydoc('test.test_pydoc.test_pydoc.nonascii', PYTHONIOENCODING='ascii')
532 encoded = nonascii.__doc__.encode('ascii', 'backslashreplace')
533 self.assertIn(encoded, result)
534
535 def test_input_strip(self):
536 missing_module = " test.i_am_not_here "
537 result = str(run_pydoc_fail(missing_module), 'ascii')
538 expected = missing_pattern % missing_module.strip()
539 self.assertEqual(expected, result)
540
541 def test_stripid(self):
542 # test with strings, other implementations might have different repr()
543 stripid = pydoc.stripid
544 # strip the id
545 self.assertEqual(stripid('<function stripid at 0x88dcee4>'),
546 '<function stripid>')
547 self.assertEqual(stripid('<function stripid at 0x01F65390>'),
548 '<function stripid>')
549 # nothing to strip, return the same text
550 self.assertEqual(stripid('42'), '42')
551 self.assertEqual(stripid("<type 'exceptions.Exception'>"),
552 "<type 'exceptions.Exception'>")
553
554 def test_builtin_with_more_than_four_children(self):
555 """Tests help on builtin object which have more than four child classes.
556
557 When running help() on a builtin class which has child classes, it
558 should contain a "Built-in subclasses" section and only 4 classes
559 should be displayed with a hint on how many more subclasses are present.
560 For example:
561
562 >>> help(object)
563 Help on class object in module builtins:
564
565 class object
566 | The most base type
567 |
568 | Built-in subclasses:
569 | async_generator
570 | BaseException
571 | builtin_function_or_method
572 | bytearray
573 | ... and 82 other subclasses
574 """
575 doc = pydoc.TextDoc()
576 try:
577 # Make sure HeapType, which has no __module__ attribute, is one
578 # of the known subclasses of object. (doc.docclass() used to
579 # fail if HeapType was imported before running this test, like
580 # when running tests sequentially.)
581 from _testcapi import HeapType
582 except ImportError:
583 pass
584 text = doc.docclass(object)
585 snip = (" | Built-in subclasses:\n"
586 " | async_generator\n"
587 " | BaseException\n"
588 " | builtin_function_or_method\n"
589 " | bytearray\n"
590 " | ... and \\d+ other subclasses")
591 self.assertRegex(text, snip)
592
593 def test_builtin_with_child(self):
594 """Tests help on builtin object which have only child classes.
595
596 When running help() on a builtin class which has child classes, it
597 should contain a "Built-in subclasses" section. For example:
598
599 >>> help(ArithmeticError)
600 Help on class ArithmeticError in module builtins:
601
602 class ArithmeticError(Exception)
603 | Base class for arithmetic errors.
604 |
605 ...
606 |
607 | Built-in subclasses:
608 | FloatingPointError
609 | OverflowError
610 | ZeroDivisionError
611 """
612 doc = pydoc.TextDoc()
613 text = doc.docclass(ArithmeticError)
614 snip = (" | Built-in subclasses:\n"
615 " | FloatingPointError\n"
616 " | OverflowError\n"
617 " | ZeroDivisionError")
618 self.assertIn(snip, text)
619
620 def test_builtin_with_grandchild(self):
621 """Tests help on builtin classes which have grandchild classes.
622
623 When running help() on a builtin class which has child classes, it
624 should contain a "Built-in subclasses" section. However, if it also has
625 grandchildren, these should not show up on the subclasses section.
626 For example:
627
628 >>> help(Exception)
629 Help on class Exception in module builtins:
630
631 class Exception(BaseException)
632 | Common base class for all non-exit exceptions.
633 |
634 ...
635 |
636 | Built-in subclasses:
637 | ArithmeticError
638 | AssertionError
639 | AttributeError
640 ...
641 """
642 doc = pydoc.TextDoc()
643 text = doc.docclass(Exception)
644 snip = (" | Built-in subclasses:\n"
645 " | ArithmeticError\n"
646 " | AssertionError\n"
647 " | AttributeError")
648 self.assertIn(snip, text)
649 # Testing that the grandchild ZeroDivisionError does not show up
650 self.assertNotIn('ZeroDivisionError', text)
651
652 def test_builtin_no_child(self):
653 """Tests help on builtin object which have no child classes.
654
655 When running help() on a builtin class which has no child classes, it
656 should not contain any "Built-in subclasses" section. For example:
657
658 >>> help(ZeroDivisionError)
659
660 Help on class ZeroDivisionError in module builtins:
661
662 class ZeroDivisionError(ArithmeticError)
663 | Second argument to a division or modulo operation was zero.
664 |
665 | Method resolution order:
666 | ZeroDivisionError
667 | ArithmeticError
668 | Exception
669 | BaseException
670 | object
671 |
672 | Methods defined here:
673 ...
674 """
675 doc = pydoc.TextDoc()
676 text = doc.docclass(ZeroDivisionError)
677 # Testing that the subclasses section does not appear
678 self.assertNotIn('Built-in subclasses', text)
679
680 def test_builtin_on_metaclasses(self):
681 """Tests help on metaclasses.
682
683 When running help() on a metaclasses such as type, it
684 should not contain any "Built-in subclasses" section.
685 """
686 doc = pydoc.TextDoc()
687 text = doc.docclass(type)
688 # Testing that the subclasses section does not appear
689 self.assertNotIn('Built-in subclasses', text)
690
691 def test_fail_help_cli(self):
692 elines = (missing_pattern % 'abd').splitlines()
693 with spawn_python("-c" "help()") as proc:
694 out, _ = proc.communicate(b"abd")
695 olines = out.decode().splitlines()[-9:-6]
696 olines[0] = olines[0].removeprefix('help> ')
697 self.assertEqual(elines, olines)
698
699 def test_fail_help_output_redirect(self):
700 with StringIO() as buf:
701 helper = pydoc.Helper(output=buf)
702 helper.help("abd")
703 expected = missing_pattern % "abd"
704 self.assertEqual(expected, buf.getvalue().strip().replace('\n', os.linesep))
705
706 @unittest.skipIf(hasattr(sys, 'gettrace') and sys.gettrace(),
707 'trace function introduces __locals__ unexpectedly')
708 @unittest.mock.patch('pydoc.pager')
709 @requires_docstrings
710 def test_help_output_redirect(self, pager_mock):
711 # issue 940286, if output is set in Helper, then all output from
712 # Helper.help should be redirected
713 self.maxDiff = None
714
715 unused, doc_loc = get_pydoc_text(pydoc_mod)
716 module = "test.test_pydoc.pydoc_mod"
717 help_header = """
718 Help on module test.test_pydoc.pydoc_mod in test.test_pydoc:
719
720 """.lstrip()
721 help_header = textwrap.dedent(help_header)
722 expected_help_pattern = help_header + expected_text_pattern
723
724 with captured_stdout() as output, captured_stderr() as err:
725 buf = StringIO()
726 helper = pydoc.Helper(output=buf)
727 helper.help(module)
728 result = buf.getvalue().strip()
729 expected_text = expected_help_pattern % (
730 (doc_loc,) +
731 expected_text_data_docstrings +
732 (inspect.getabsfile(pydoc_mod),))
733 self.assertEqual('', output.getvalue())
734 self.assertEqual('', err.getvalue())
735 self.assertEqual(expected_text, result)
736
737 pager_mock.assert_not_called()
738
739 @unittest.skipIf(hasattr(sys, 'gettrace') and sys.gettrace(),
740 'trace function introduces __locals__ unexpectedly')
741 @requires_docstrings
742 @unittest.mock.patch('pydoc.pager')
743 def test_help_output_redirect_various_requests(self, pager_mock):
744 # issue 940286, if output is set in Helper, then all output from
745 # Helper.help should be redirected
746
747 def run_pydoc_for_request(request, expected_text_part):
748 """Helper function to run pydoc with its output redirected"""
749 with captured_stdout() as output, captured_stderr() as err:
750 buf = StringIO()
751 helper = pydoc.Helper(output=buf)
752 helper.help(request)
753 result = buf.getvalue().strip()
754 self.assertEqual('', output.getvalue(), msg=f'failed on request "{request}"')
755 self.assertEqual('', err.getvalue(), msg=f'failed on request "{request}"')
756 self.assertIn(expected_text_part, result, msg=f'failed on request "{request}"')
757 pager_mock.assert_not_called()
758
759 self.maxDiff = None
760
761 # test for "keywords"
762 run_pydoc_for_request('keywords', 'Here is a list of the Python keywords.')
763 # test for "symbols"
764 run_pydoc_for_request('symbols', 'Here is a list of the punctuation symbols')
765 # test for "topics"
766 run_pydoc_for_request('topics', 'Here is a list of available topics.')
767 # test for "modules" skipped, see test_modules()
768 # test for symbol "%"
769 run_pydoc_for_request('%', 'The power operator')
770 # test for special True, False, None keywords
771 run_pydoc_for_request('True', 'class bool(int)')
772 run_pydoc_for_request('False', 'class bool(int)')
773 run_pydoc_for_request('None', 'class NoneType(object)')
774 # test for keyword "assert"
775 run_pydoc_for_request('assert', 'The "assert" statement')
776 # test for topic "TYPES"
777 run_pydoc_for_request('TYPES', 'The standard type hierarchy')
778 # test for "pydoc.Helper.help"
779 run_pydoc_for_request('pydoc.Helper.help', 'Help on function help in pydoc.Helper:')
780 # test for pydoc.Helper.help
781 run_pydoc_for_request(pydoc.Helper.help, 'Help on function help in module pydoc:')
782 # test for pydoc.Helper() instance skipped because it is always meant to be interactive
783
784 @unittest.skipIf(hasattr(sys, 'gettrace') and sys.gettrace(),
785 'trace function introduces __locals__ unexpectedly')
786 @requires_docstrings
787 def test_help_output_pager(self):
788 def run_pydoc_pager(request, what, expected_first_line):
789 with (captured_stdout() as output,
790 captured_stderr() as err,
791 unittest.mock.patch('pydoc.pager') as pager_mock,
792 self.subTest(repr(request))):
793 helper = pydoc.Helper()
794 helper.help(request)
795 self.assertEqual('', err.getvalue())
796 self.assertEqual('\n', output.getvalue())
797 pager_mock.assert_called_once()
798 result = clean_text(pager_mock.call_args.args[0])
799 self.assertEqual(result.splitlines()[0], expected_first_line)
800 self.assertEqual(pager_mock.call_args.args[1], f'Help on {what}')
801
802 run_pydoc_pager('%', 'EXPRESSIONS', 'Operator precedence')
803 run_pydoc_pager('True', 'bool object', 'Help on bool object:')
804 run_pydoc_pager(True, 'bool object', 'Help on bool object:')
805 run_pydoc_pager('assert', 'assert', 'The "assert" statement')
806 run_pydoc_pager('TYPES', 'TYPES', 'The standard type hierarchy')
807 run_pydoc_pager('pydoc.Helper.help', 'pydoc.Helper.help',
808 'Help on function help in pydoc.Helper:')
809 run_pydoc_pager(pydoc.Helper.help, 'Helper.help',
810 'Help on function help in module pydoc:')
811 run_pydoc_pager('str', 'str', 'Help on class str in module builtins:')
812 run_pydoc_pager(str, 'str', 'Help on class str in module builtins:')
813 run_pydoc_pager('str.upper', 'str.upper',
814 'Help on method descriptor upper in str:')
815 run_pydoc_pager(str.upper, 'str.upper',
816 'Help on method descriptor upper:')
817 run_pydoc_pager(''.upper, 'str.upper',
818 'Help on built-in function upper:')
819 run_pydoc_pager(str.__add__,
820 'str.__add__', 'Help on method descriptor __add__:')
821 run_pydoc_pager(''.__add__,
822 'str.__add__', 'Help on method wrapper __add__:')
823 run_pydoc_pager(int.numerator, 'int.numerator',
824 'Help on getset descriptor builtins.int.numerator:')
825 run_pydoc_pager(list[int], 'list',
826 'Help on GenericAlias in module builtins:')
827 run_pydoc_pager('sys', 'sys', 'Help on built-in module sys:')
828 run_pydoc_pager(sys, 'sys', 'Help on built-in module sys:')
829
830 def test_showtopic(self):
831 with captured_stdout() as showtopic_io:
832 helper = pydoc.Helper()
833 helper.showtopic('with')
834 helptext = showtopic_io.getvalue()
835 self.assertIn('The "with" statement', helptext)
836
837 def test_fail_showtopic(self):
838 with captured_stdout() as showtopic_io:
839 helper = pydoc.Helper()
840 helper.showtopic('abd')
841 expected = "no documentation found for 'abd'"
842 self.assertEqual(expected, showtopic_io.getvalue().strip())
843
844 @unittest.mock.patch('pydoc.pager')
845 def test_fail_showtopic_output_redirect(self, pager_mock):
846 with StringIO() as buf:
847 helper = pydoc.Helper(output=buf)
848 helper.showtopic("abd")
849 expected = "no documentation found for 'abd'"
850 self.assertEqual(expected, buf.getvalue().strip())
851
852 pager_mock.assert_not_called()
853
854 @unittest.skipIf(hasattr(sys, 'gettrace') and sys.gettrace(),
855 'trace function introduces __locals__ unexpectedly')
856 @requires_docstrings
857 @unittest.mock.patch('pydoc.pager')
858 def test_showtopic_output_redirect(self, pager_mock):
859 # issue 940286, if output is set in Helper, then all output from
860 # Helper.showtopic should be redirected
861 self.maxDiff = None
862
863 with captured_stdout() as output, captured_stderr() as err:
864 buf = StringIO()
865 helper = pydoc.Helper(output=buf)
866 helper.showtopic('with')
867 result = buf.getvalue().strip()
868 self.assertEqual('', output.getvalue())
869 self.assertEqual('', err.getvalue())
870 self.assertIn('The "with" statement', result)
871
872 pager_mock.assert_not_called()
873
874 def test_lambda_with_return_annotation(self):
875 func = lambda a, b, c: 1
876 func.__annotations__ = {"return": int}
877 with captured_stdout() as help_io:
878 pydoc.help(func)
879 helptext = help_io.getvalue()
880 self.assertIn("lambda (a, b, c) -> int", helptext)
881
882 def test_lambda_without_return_annotation(self):
883 func = lambda a, b, c: 1
884 func.__annotations__ = {"a": int, "b": int, "c": int}
885 with captured_stdout() as help_io:
886 pydoc.help(func)
887 helptext = help_io.getvalue()
888 self.assertIn("lambda (a: int, b: int, c: int)", helptext)
889
890 def test_lambda_with_return_and_params_annotation(self):
891 func = lambda a, b, c: 1
892 func.__annotations__ = {"a": int, "b": int, "c": int, "return": int}
893 with captured_stdout() as help_io:
894 pydoc.help(func)
895 helptext = help_io.getvalue()
896 self.assertIn("lambda (a: int, b: int, c: int) -> int", helptext)
897
898 def test_namedtuple_fields(self):
899 Person = namedtuple('Person', ['nickname', 'firstname'])
900 with captured_stdout() as help_io:
901 pydoc.help(Person)
902 helptext = help_io.getvalue()
903 self.assertIn("nickname", helptext)
904 self.assertIn("firstname", helptext)
905 self.assertIn("Alias for field number 0", helptext)
906 self.assertIn("Alias for field number 1", helptext)
907
908 def test_namedtuple_public_underscore(self):
909 NT = namedtuple('NT', ['abc', 'def'], rename=True)
910 with captured_stdout() as help_io:
911 pydoc.help(NT)
912 helptext = help_io.getvalue()
913 self.assertIn('_1', helptext)
914 self.assertIn('_replace', helptext)
915 self.assertIn('_asdict', helptext)
916
917 def test_synopsis(self):
918 self.addCleanup(unlink, TESTFN)
919 for encoding in ('ISO-8859-1', 'UTF-8'):
920 with open(TESTFN, 'w', encoding=encoding) as script:
921 if encoding != 'UTF-8':
922 print('#coding: {}'.format(encoding), file=script)
923 print('"""line 1: h\xe9', file=script)
924 print('line 2: hi"""', file=script)
925 synopsis = pydoc.synopsis(TESTFN, {})
926 self.assertEqual(synopsis, 'line 1: h\xe9')
927
928 def test_source_synopsis(self):
929 def check(source, expected, encoding=None):
930 if isinstance(source, str):
931 source_file = StringIO(source)
932 else:
933 source_file = io.TextIOWrapper(io.BytesIO(source), encoding=encoding)
934 with source_file:
935 result = pydoc.source_synopsis(source_file)
936 self.assertEqual(result, expected)
937
938 check('"""Single line docstring."""',
939 'Single line docstring.')
940 check('"""First line of docstring.\nSecond line.\nThird line."""',
941 'First line of docstring.')
942 check('"""First line of docstring.\\nSecond line.\\nThird line."""',
943 'First line of docstring.')
944 check('""" Whitespace around docstring. """',
945 'Whitespace around docstring.')
946 check('import sys\n"""No docstring"""',
947 None)
948 check(' \n"""Docstring after empty line."""',
949 'Docstring after empty line.')
950 check('# Comment\n"""Docstring after comment."""',
951 'Docstring after comment.')
952 check(' # Indented comment\n"""Docstring after comment."""',
953 'Docstring after comment.')
954 check('""""""', # Empty docstring
955 '')
956 check('', # Empty file
957 None)
958 check('"""Embedded\0null byte"""',
959 None)
960 check('"""Embedded null byte"""\0',
961 None)
962 check('"""Café and résumé."""',
963 'Café and résumé.')
964 check("'''Triple single quotes'''",
965 'Triple single quotes')
966 check('"Single double quotes"',
967 'Single double quotes')
968 check("'Single single quotes'",
969 'Single single quotes')
970 check('"""split\\\nline"""',
971 'splitline')
972 check('"""Unrecognized escape \\sequence"""',
973 'Unrecognized escape \\sequence')
974 check('"""Invalid escape seq\\uence"""',
975 None)
976 check('r"""Raw \\stri\\ng"""',
977 'Raw \\stri\\ng')
978 check('b"""Bytes literal"""',
979 None)
980 check('f"""f-string"""',
981 None)
982 check('"""Concatenated""" \\\n"string" \'literals\'',
983 'Concatenatedstringliterals')
984 check('"""String""" + """expression"""',
985 None)
986 check('("""In parentheses""")',
987 'In parentheses')
988 check('("""Multiple lines """\n"""in parentheses""")',
989 'Multiple lines in parentheses')
990 check('()', # tuple
991 None)
992 check(b'# coding: iso-8859-15\n"""\xa4uro sign"""',
993 '€uro sign', encoding='iso-8859-15')
994 check(b'"""\xa4"""', # Decoding error
995 None, encoding='utf-8')
996
997 with tempfile.NamedTemporaryFile(mode='w+', encoding='utf-8') as temp_file:
998 temp_file.write('"""Real file test."""\n')
999 temp_file.flush()
1000 temp_file.seek(0)
1001 result = pydoc.source_synopsis(temp_file)
1002 self.assertEqual(result, "Real file test.")
1003
1004 @requires_docstrings
1005 def test_synopsis_sourceless(self):
1006 os = import_helper.import_fresh_module('os')
1007 expected = os.__doc__.splitlines()[0]
1008 filename = os.__spec__.cached
1009 synopsis = pydoc.synopsis(filename)
1010
1011 self.assertEqual(synopsis, expected)
1012
1013 def test_synopsis_sourceless_empty_doc(self):
1014 with os_helper.temp_cwd() as test_dir:
1015 init_path = os.path.join(test_dir, 'foomod42.py')
1016 cached_path = importlib.util.cache_from_source(init_path)
1017 with open(init_path, 'w') as fobj:
1018 fobj.write("foo = 1")
1019 py_compile.compile(init_path)
1020 synopsis = pydoc.synopsis(init_path, {})
1021 self.assertIsNone(synopsis)
1022 synopsis_cached = pydoc.synopsis(cached_path, {})
1023 self.assertIsNone(synopsis_cached)
1024
1025 def test_splitdoc_with_description(self):
1026 example_string = "I Am A Doc\n\n\nHere is my description"
1027 self.assertEqual(pydoc.splitdoc(example_string),
1028 ('I Am A Doc', '\nHere is my description'))
1029
1030 def test_is_package_when_not_package(self):
1031 with os_helper.temp_cwd() as test_dir:
1032 with self.assertWarns(DeprecationWarning) as cm:
1033 self.assertFalse(pydoc.ispackage(test_dir))
1034 self.assertEqual(cm.filename, __file__)
1035
1036 def test_is_package_when_is_package(self):
1037 with os_helper.temp_cwd() as test_dir:
1038 init_path = os.path.join(test_dir, '__init__.py')
1039 open(init_path, 'w').close()
1040 with self.assertWarns(DeprecationWarning) as cm:
1041 self.assertTrue(pydoc.ispackage(test_dir))
1042 os.remove(init_path)
1043 self.assertEqual(cm.filename, __file__)
1044
1045 def test_allmethods(self):
1046 # issue 17476: allmethods was no longer returning unbound methods.
1047 # This test is a bit fragile in the face of changes to object and type,
1048 # but I can't think of a better way to do it without duplicating the
1049 # logic of the function under test.
1050
1051 class TestClass(object):
1052 def method_returning_true(self):
1053 return True
1054
1055 # What we expect to get back: everything on object...
1056 expected = dict(vars(object))
1057 # ...plus our unbound method...
1058 expected['method_returning_true'] = TestClass.method_returning_true
1059 # ...but not the non-methods on object.
1060 del expected['__doc__']
1061 del expected['__class__']
1062 # inspect resolves descriptors on type into methods, but vars doesn't,
1063 # so we need to update __subclasshook__ and __init_subclass__.
1064 expected['__subclasshook__'] = TestClass.__subclasshook__
1065 expected['__init_subclass__'] = TestClass.__init_subclass__
1066
1067 methods = pydoc.allmethods(TestClass)
1068 self.assertDictEqual(methods, expected)
1069
1070 @requires_docstrings
1071 def test_method_aliases(self):
1072 class A:
1073 def tkraise(self, aboveThis=None):
1074 """Raise this widget in the stacking order."""
1075 lift = tkraise
1076 def a_size(self):
1077 """Return size"""
1078 class B(A):
1079 def itemconfigure(self, tagOrId, cnf=None, **kw):
1080 """Configure resources of an item TAGORID."""
1081 itemconfig = itemconfigure
1082 b_size = A.a_size
1083
1084 doc = pydoc.render_doc(B)
1085 doc = clean_text(doc)
1086 self.assertEqual(doc, '''\
1087 Python Library Documentation: class B in module %s
1088
1089 class B(A)
1090 | Method resolution order:
1091 | B
1092 | A
1093 | builtins.object
1094 |
1095 | Methods defined here:
1096 |
1097 | b_size = a_size(self)
1098 |
1099 | itemconfig = itemconfigure(self, tagOrId, cnf=None, **kw)
1100 |
1101 | itemconfigure(self, tagOrId, cnf=None, **kw)
1102 | Configure resources of an item TAGORID.
1103 |
1104 | ----------------------------------------------------------------------
1105 | Methods inherited from A:
1106 |
1107 | a_size(self)
1108 | Return size
1109 |
1110 | lift = tkraise(self, aboveThis=None)
1111 |
1112 | tkraise(self, aboveThis=None)
1113 | Raise this widget in the stacking order.
1114 |
1115 | ----------------------------------------------------------------------
1116 | Data descriptors inherited from A:
1117 |
1118 | __dict__
1119 | dictionary for instance variables
1120 |
1121 | __weakref__
1122 | list of weak references to the object
1123 ''' % __name__)
1124
1125 doc = pydoc.render_doc(B, renderer=pydoc.HTMLDoc())
1126 expected_text = f"""
1127 Python Library Documentation
1128
1129 class B in module {__name__}
1130 class B(A)
1131 Method resolution order:
1132 B
1133 A
1134 builtins.object
1135
1136 Methods defined here:
1137 b_size = a_size(self)
1138 itemconfig = itemconfigure(self, tagOrId, cnf=None, **kw)
1139 itemconfigure(self, tagOrId, cnf=None, **kw)
1140 Configure resources of an item TAGORID.
1141
1142 Methods inherited from A:
1143 a_size(self)
1144 Return size
1145 lift = tkraise(self, aboveThis=None)
1146 tkraise(self, aboveThis=None)
1147 Raise this widget in the stacking order.
1148
1149 Data descriptors inherited from A:
1150 __dict__
1151 dictionary for instance variables
1152 __weakref__
1153 list of weak references to the object
1154 """
1155 as_text = html2text(doc)
1156 expected_lines = [line.strip() for line in expected_text.split("\n") if line]
1157 for expected_line in expected_lines:
1158 self.assertIn(expected_line, as_text)
1159
1160 def test_long_signatures(self):
1161 from collections.abc import Callable
1162 from typing import Literal, Annotated
1163
1164 class A:
1165 def __init__(self,
1166 arg1: Callable[[int, int, int], str],
1167 arg2: Literal['some value', 'other value'],
1168 arg3: Annotated[int, 'some docs about this type'],
1169 ) -> None:
1170 ...
1171
1172 doc = pydoc.render_doc(A)
1173 doc = clean_text(doc)
1174 self.assertEqual(doc, '''Python Library Documentation: class A in module %s
1175
1176 class A(builtins.object)
1177 | A(
1178 | arg1: Callable[[int, int, int], str],
1179 | arg2: Literal['some value', 'other value'],
1180 | arg3: Annotated[int, 'some docs about this type']
1181 | ) -> None
1182 |
1183 | Methods defined here:
1184 |
1185 | __init__(
1186 | self,
1187 | arg1: Callable[[int, int, int], str],
1188 | arg2: Literal['some value', 'other value'],
1189 | arg3: Annotated[int, 'some docs about this type']
1190 | ) -> None
1191 |
1192 | ----------------------------------------------------------------------
1193 | Data descriptors defined here:
1194 |
1195 | __dict__%s
1196 |
1197 | __weakref__%s
1198 ''' % (__name__,
1199 '' if MISSING_C_DOCSTRINGS else '\n | dictionary for instance variables',
1200 '' if MISSING_C_DOCSTRINGS else '\n | list of weak references to the object',
1201 ))
1202
1203 def func(
1204 arg1: Callable[[Annotated[int, 'Some doc']], str],
1205 arg2: Literal[1, 2, 3, 4, 5, 6, 7, 8],
1206 ) -> Annotated[int, 'Some other']:
1207 ...
1208
1209 doc = pydoc.render_doc(func)
1210 doc = clean_text(doc)
1211 self.assertEqual(doc, '''Python Library Documentation: function func in module %s
1212
1213 func(
1214 arg1: Callable[[Annotated[int, 'Some doc']], str],
1215 arg2: Literal[1, 2, 3, 4, 5, 6, 7, 8]
1216 ) -> Annotated[int, 'Some other']
1217 ''' % __name__)
1218
1219 def function_with_really_long_name_so_annotations_can_be_rather_small(
1220 arg1: int,
1221 arg2: str,
1222 ):
1223 ...
1224
1225 doc = pydoc.render_doc(function_with_really_long_name_so_annotations_can_be_rather_small)
1226 doc = clean_text(doc)
1227 self.assertEqual(doc, '''Python Library Documentation: function function_with_really_long_name_so_annotations_can_be_rather_small in module %s
1228
1229 function_with_really_long_name_so_annotations_can_be_rather_small(
1230 arg1: int,
1231 arg2: str
1232 )
1233 ''' % __name__)
1234
1235 does_not_have_name = lambda \
1236 very_long_parameter_name_that_should_not_fit_into_a_single_line, \
1237 second_very_long_parameter_name: ...
1238
1239 doc = pydoc.render_doc(does_not_have_name)
1240 doc = clean_text(doc)
1241 self.assertEqual(doc, '''Python Library Documentation: function <lambda> in module %s
1242
1243 <lambda> lambda very_long_parameter_name_that_should_not_fit_into_a_single_line, second_very_long_parameter_name
1244 ''' % __name__)
1245
1246 def test__future__imports(self):
1247 # __future__ features are excluded from module help,
1248 # except when it's the __future__ module itself
1249 import __future__
1250 future_text, _ = get_pydoc_text(__future__)
1251 future_html, _ = get_pydoc_html(__future__)
1252 pydoc_mod_text, _ = get_pydoc_text(pydoc_mod)
1253 pydoc_mod_html, _ = get_pydoc_html(pydoc_mod)
1254
1255 for feature in __future__.all_feature_names:
1256 txt = f"{feature} = _Feature"
1257 html = f"<strong>{feature}</strong> = _Feature"
1258 self.assertIn(txt, future_text)
1259 self.assertIn(html, future_html)
1260 self.assertNotIn(txt, pydoc_mod_text)
1261 self.assertNotIn(html, pydoc_mod_html)
1262
1263
1264 class PydocImportTest(PydocBaseTest):
1265
1266 def setUp(self):
1267 self.test_dir = os.mkdir(TESTFN)
1268 self.addCleanup(rmtree, TESTFN)
1269 importlib.invalidate_caches()
1270
1271 def test_badimport(self):
1272 # This tests the fix for issue 5230, where if pydoc found the module
1273 # but the module had an internal import error pydoc would report no doc
1274 # found.
1275 modname = 'testmod_xyzzy'
1276 testpairs = (
1277 ('i_am_not_here', 'i_am_not_here'),
1278 ('test.i_am_not_here_either', 'test.i_am_not_here_either'),
1279 ('test.i_am_not_here.neither_am_i', 'test.i_am_not_here'),
1280 ('i_am_not_here.{}'.format(modname), 'i_am_not_here'),
1281 ('test.{}'.format(modname), 'test.{}'.format(modname)),
1282 )
1283
1284 sourcefn = os.path.join(TESTFN, modname) + os.extsep + "py"
1285 for importstring, expectedinmsg in testpairs:
1286 with open(sourcefn, 'w') as f:
1287 f.write("import {}\n".format(importstring))
1288 result = run_pydoc_fail(modname, PYTHONPATH=TESTFN).decode("ascii")
1289 expected = badimport_pattern % (modname, expectedinmsg)
1290 self.assertEqual(expected, result)
1291
1292 def test_apropos_with_bad_package(self):
1293 # Issue 7425 - pydoc -k failed when bad package on path
1294 pkgdir = os.path.join(TESTFN, "syntaxerr")
1295 os.mkdir(pkgdir)
1296 badsyntax = os.path.join(pkgdir, "__init__") + os.extsep + "py"
1297 with open(badsyntax, 'w') as f:
1298 f.write("invalid python syntax = $1\n")
1299 with self.restrict_walk_packages(path=[TESTFN]):
1300 with captured_stdout() as out:
1301 with captured_stderr() as err:
1302 pydoc.apropos('xyzzy')
1303 # No result, no error
1304 self.assertEqual(out.getvalue(), '')
1305 self.assertEqual(err.getvalue(), '')
1306 # The package name is still matched
1307 with captured_stdout() as out:
1308 with captured_stderr() as err:
1309 pydoc.apropos('syntaxerr')
1310 self.assertEqual(out.getvalue().strip(), 'syntaxerr')
1311 self.assertEqual(err.getvalue(), '')
1312
1313 def test_apropos_with_unreadable_dir(self):
1314 # Issue 7367 - pydoc -k failed when unreadable dir on path
1315 self.unreadable_dir = os.path.join(TESTFN, "unreadable")
1316 os.mkdir(self.unreadable_dir, 0)
1317 self.addCleanup(os.rmdir, self.unreadable_dir)
1318 # Note, on Windows the directory appears to be still
1319 # readable so this is not really testing the issue there
1320 with self.restrict_walk_packages(path=[TESTFN]):
1321 with captured_stdout() as out:
1322 with captured_stderr() as err:
1323 pydoc.apropos('SOMEKEY')
1324 # No result, no error
1325 self.assertEqual(out.getvalue(), '')
1326 self.assertEqual(err.getvalue(), '')
1327
1328 def test_apropos_empty_doc(self):
1329 pkgdir = os.path.join(TESTFN, 'walkpkg')
1330 os.mkdir(pkgdir)
1331 self.addCleanup(rmtree, pkgdir)
1332 init_path = os.path.join(pkgdir, '__init__.py')
1333 with open(init_path, 'w') as fobj:
1334 fobj.write("foo = 1")
1335 with self.restrict_walk_packages(path=[TESTFN]), captured_stdout() as stdout:
1336 pydoc.apropos('')
1337 self.assertIn('walkpkg', stdout.getvalue())
1338
1339 def test_url_search_package_error(self):
1340 # URL handler search should cope with packages that raise exceptions
1341 pkgdir = os.path.join(TESTFN, "test_error_package")
1342 os.mkdir(pkgdir)
1343 init = os.path.join(pkgdir, "__init__.py")
1344 with open(init, "wt", encoding="ascii") as f:
1345 f.write("""raise ValueError("ouch")\n""")
1346 with self.restrict_walk_packages(path=[TESTFN]):
1347 # Package has to be importable for the error to have any effect
1348 saved_paths = tuple(sys.path)
1349 sys.path.insert(0, TESTFN)
1350 try:
1351 with self.assertRaisesRegex(ValueError, "ouch"):
1352 # Sanity check
1353 import test_error_package # noqa: F401
1354
1355 text = self.call_url_handler("search?key=test_error_package",
1356 "Pydoc: Search Results")
1357 found = ('<a href="test_error_package.html">'
1358 'test_error_package</a>')
1359 self.assertIn(found, text)
1360 finally:
1361 sys.path[:] = saved_paths
1362
1363 @unittest.skip('causes undesirable side-effects (#20128)')
1364 def test_modules(self):
1365 # See Helper.listmodules().
1366 num_header_lines = 2
1367 num_module_lines_min = 5 # Playing it safe.
1368 num_footer_lines = 3
1369 expected = num_header_lines + num_module_lines_min + num_footer_lines
1370
1371 output = StringIO()
1372 helper = pydoc.Helper(output=output)
1373 helper('modules')
1374 result = output.getvalue().strip()
1375 num_lines = len(result.splitlines())
1376
1377 self.assertGreaterEqual(num_lines, expected)
1378
1379 @unittest.skip('causes undesirable side-effects (#20128)')
1380 def test_modules_search(self):
1381 # See Helper.listmodules().
1382 expected = 'pydoc - '
1383
1384 output = StringIO()
1385 helper = pydoc.Helper(output=output)
1386 with captured_stdout() as help_io:
1387 helper('modules pydoc')
1388 result = help_io.getvalue()
1389
1390 self.assertIn(expected, result)
1391
1392 @unittest.skip('some buildbots are not cooperating (#20128)')
1393 def test_modules_search_builtin(self):
1394 expected = 'gc - '
1395
1396 output = StringIO()
1397 helper = pydoc.Helper(output=output)
1398 with captured_stdout() as help_io:
1399 helper('modules garbage')
1400 result = help_io.getvalue()
1401
1402 self.assertStartsWith(result, expected)
1403
1404 def test_importfile(self):
1405 try:
1406 loaded_pydoc = pydoc.importfile(pydoc.__file__)
1407
1408 self.assertIsNot(loaded_pydoc, pydoc)
1409 self.assertEqual(loaded_pydoc.__name__, 'pydoc')
1410 self.assertEqual(loaded_pydoc.__file__, pydoc.__file__)
1411 self.assertEqual(loaded_pydoc.__spec__, pydoc.__spec__)
1412 finally:
1413 sys.modules['pydoc'] = pydoc
1414
1415
1416 class Rect:
1417 @property
1418 def area(self):
1419 '''Area of the rect'''
1420 return self.w * self.h
1421
1422
1423 class Square(Rect):
1424 area = property(lambda self: self.side**2)
1425
1426
1427 class TestDescriptions(unittest.TestCase):
1428 def tearDown(self):
1429 self.assertIs(sys.modules['pydoc'], pydoc)
1430
1431 def test_module(self):
1432 # Check that pydocfodder module can be described
1433 doc = pydoc.render_doc(pydocfodder)
1434 self.assertIn("pydocfodder", doc)
1435
1436 def test_class(self):
1437 class C: "New-style class"
1438 c = C()
1439
1440 self.assertEqual(pydoc.describe(C), 'class C')
1441 self.assertEqual(pydoc.describe(c), 'C')
1442 expected = 'C in module %s object' % __name__
1443 self.assertIn(expected, pydoc.render_doc(c))
1444
1445 def test_generic_alias(self):
1446 self.assertEqual(pydoc.describe(typing.List[int]), '_GenericAlias')
1447 doc = pydoc.render_doc(typing.List[int], renderer=pydoc.plaintext)
1448 self.assertIn('_GenericAlias in module typing', doc)
1449 self.assertIn('List = class list(object)', doc)
1450 if not MISSING_C_DOCSTRINGS:
1451 self.assertIn(list.__doc__.strip().splitlines()[0], doc)
1452
1453 self.assertEqual(pydoc.describe(list[int]), 'GenericAlias')
1454 doc = pydoc.render_doc(list[int], renderer=pydoc.plaintext)
1455 self.assertIn('GenericAlias in module builtins', doc)
1456 self.assertIn('\nclass list(object)', doc)
1457 if not MISSING_C_DOCSTRINGS:
1458 self.assertIn(list.__doc__.strip().splitlines()[0], doc)
1459
1460 def test_union_type(self):
1461 self.assertEqual(pydoc.describe(typing.Union[int, str]), 'Union')
1462 doc = pydoc.render_doc(typing.Union[int, str], renderer=pydoc.plaintext)
1463 self.assertIn('Union in module typing', doc)
1464 self.assertIn('class Union(builtins.object)', doc)
1465 if typing.Union.__doc__:
1466 self.assertIn(typing.Union.__doc__.strip().splitlines()[0], doc)
1467
1468 self.assertEqual(pydoc.describe(int | str), 'Union')
1469 doc = pydoc.render_doc(int | str, renderer=pydoc.plaintext)
1470 self.assertIn('Union in module typing', doc)
1471 self.assertIn('class Union(builtins.object)', doc)
1472 if not MISSING_C_DOCSTRINGS:
1473 self.assertIn(types.UnionType.__doc__.strip().splitlines()[0], doc)
1474
1475 def test_special_form(self):
1476 self.assertEqual(pydoc.describe(typing.NoReturn), '_SpecialForm')
1477 doc = pydoc.render_doc(typing.NoReturn, renderer=pydoc.plaintext)
1478 self.assertIn('_SpecialForm in module typing', doc)
1479 if typing.NoReturn.__doc__:
1480 self.assertIn('NoReturn = typing.NoReturn', doc)
1481 self.assertIn(typing.NoReturn.__doc__.strip().splitlines()[0], doc)
1482 else:
1483 self.assertIn('NoReturn = class _SpecialForm(_Final)', doc)
1484
1485 def test_typing_pydoc(self):
1486 def foo(data: typing.List[typing.Any],
1487 x: int) -> typing.Iterator[typing.Tuple[int, typing.Any]]:
1488 ...
1489 T = typing.TypeVar('T')
1490 class C(typing.Generic[T], typing.Mapping[int, str]): ...
1491 self.assertEqual(pydoc.render_doc(foo).splitlines()[-1],
1492 'f\x08fo\x08oo\x08o(data: typing.List[typing.Any], x: int)'
1493 ' -> typing.Iterator[typing.Tuple[int, typing.Any]]')
1494 self.assertEqual(pydoc.render_doc(C).splitlines()[2],
1495 'class C\x08C(collections.abc.Mapping, typing.Generic)')
1496
1497 def test_builtin(self):
1498 for name in ('str', 'str.translate', 'builtins.str',
1499 'builtins.str.translate'):
1500 # test low-level function
1501 self.assertIsNotNone(pydoc.locate(name))
1502 # test high-level function
1503 try:
1504 pydoc.render_doc(name)
1505 except ImportError:
1506 self.fail('finding the doc of {!r} failed'.format(name))
1507
1508 for name in ('notbuiltins', 'strrr', 'strr.translate',
1509 'str.trrrranslate', 'builtins.strrr',
1510 'builtins.str.trrranslate'):
1511 self.assertIsNone(pydoc.locate(name))
1512 self.assertRaises(ImportError, pydoc.render_doc, name)
1513
1514 @staticmethod
1515 def _get_summary_line(o):
1516 text = pydoc.plain(pydoc.render_doc(o))
1517 lines = text.split('\n')
1518 assert len(lines) >= 2
1519 return lines[2]
1520
1521 @staticmethod
1522 def _get_summary_lines(o):
1523 text = pydoc.plain(pydoc.render_doc(o))
1524 lines = text.split('\n')
1525 return '\n'.join(lines[2:])
1526
1527 # these should include "self"
1528 def test_unbound_python_method(self):
1529 self.assertEqual(self._get_summary_line(textwrap.TextWrapper.wrap),
1530 "wrap(self, text)")
1531
1532 @requires_docstrings
1533 def test_unbound_builtin_method(self):
1534 self.assertEqual(self._get_summary_line(_pickle.Pickler.dump),
1535 "dump(self, obj, /) unbound _pickle.Pickler method")
1536
1537 # these no longer include "self"
1538 def test_bound_python_method(self):
1539 t = textwrap.TextWrapper()
1540 self.assertEqual(self._get_summary_line(t.wrap),
1541 "wrap(text) method of textwrap.TextWrapper instance")
1542 def test_field_order_for_named_tuples(self):
1543 Person = namedtuple('Person', ['nickname', 'firstname', 'agegroup'])
1544 s = pydoc.render_doc(Person)
1545 self.assertLess(s.index('nickname'), s.index('firstname'))
1546 self.assertLess(s.index('firstname'), s.index('agegroup'))
1547
1548 class NonIterableFields:
1549 _fields = None
1550
1551 class NonHashableFields:
1552 _fields = [[]]
1553
1554 # Make sure these doesn't fail
1555 pydoc.render_doc(NonIterableFields)
1556 pydoc.render_doc(NonHashableFields)
1557
1558 @requires_docstrings
1559 def test_bound_builtin_method(self):
1560 s = StringIO()
1561 p = _pickle.Pickler(s)
1562 self.assertEqual(self._get_summary_line(p.dump),
1563 "dump(obj, /) method of _pickle.Pickler instance")
1564
1565 # this should *never* include self!
1566 @requires_docstrings
1567 def test_module_level_callable(self):
1568 self.assertEqual(self._get_summary_line(os.stat),
1569 "stat(path, *, dir_fd=None, follow_symlinks=True)")
1570
1571 def test_module_level_callable_noargs(self):
1572 self.assertEqual(self._get_summary_line(time.time),
1573 "time()")
1574
1575 def test_module_level_callable_o(self):
1576 try:
1577 import _stat
1578 except ImportError:
1579 # stat.S_IMODE() and _stat.S_IMODE() have a different signature
1580 self.skipTest('_stat extension is missing')
1581
1582 self.assertEqual(self._get_summary_line(_stat.S_IMODE),
1583 "S_IMODE(object, /)")
1584
1585 def test_unbound_builtin_method_noargs(self):
1586 self.assertEqual(self._get_summary_line(str.lower),
1587 "lower(self, /) unbound builtins.str method")
1588
1589 def test_bound_builtin_method_noargs(self):
1590 self.assertEqual(self._get_summary_line(''.lower),
1591 "lower() method of builtins.str instance")
1592
1593 def test_unbound_builtin_method_o(self):
1594 self.assertEqual(self._get_summary_line(set.add),
1595 "add(self, object, /) unbound builtins.set method")
1596
1597 def test_bound_builtin_method_o(self):
1598 self.assertEqual(self._get_summary_line(set().add),
1599 "add(object, /) method of builtins.set instance")
1600
1601 def test_unbound_builtin_method_coexist_o(self):
1602 self.assertEqual(self._get_summary_line(set.__contains__),
1603 "__contains__(self, object, /) unbound builtins.set method")
1604
1605 def test_bound_builtin_method_coexist_o(self):
1606 self.assertEqual(self._get_summary_line(set().__contains__),
1607 "__contains__(object, /) method of builtins.set instance")
1608
1609 def test_unbound_builtin_classmethod_noargs(self):
1610 self.assertEqual(self._get_summary_line(datetime.datetime.__dict__['utcnow']),
1611 "utcnow(type, /) unbound datetime.datetime method")
1612
1613 def test_bound_builtin_classmethod_noargs(self):
1614 self.assertEqual(self._get_summary_line(datetime.datetime.utcnow),
1615 "utcnow() class method of datetime.datetime")
1616
1617 def test_unbound_builtin_classmethod_o(self):
1618 self.assertEqual(self._get_summary_line(dict.__dict__['__class_getitem__']),
1619 "__class_getitem__(type, object, /) unbound builtins.dict method")
1620
1621 def test_bound_builtin_classmethod_o(self):
1622 self.assertEqual(self._get_summary_line(dict.__class_getitem__),
1623 "__class_getitem__(object, /) class method of builtins.dict")
1624
1625 @support.cpython_only
1626 @requires_docstrings
1627 def test_module_level_callable_unrepresentable_default(self):
1628 _testcapi = import_helper.import_module("_testcapi")
1629 builtin = _testcapi.func_with_unrepresentable_signature
1630 self.assertEqual(self._get_summary_line(builtin),
1631 "func_with_unrepresentable_signature(a, b=<x>)")
1632
1633 @support.cpython_only
1634 @requires_docstrings
1635 def test_builtin_staticmethod_unrepresentable_default(self):
1636 self.assertEqual(self._get_summary_line(str.maketrans),
1637 "maketrans(x, y=<unrepresentable>, z=<unrepresentable>, /)")
1638 _testcapi = import_helper.import_module("_testcapi")
1639 cls = _testcapi.DocStringUnrepresentableSignatureTest
1640 self.assertEqual(self._get_summary_line(cls.staticmeth),
1641 "staticmeth(a, b=<x>)")
1642
1643 @support.cpython_only
1644 @requires_docstrings
1645 def test_unbound_builtin_method_unrepresentable_default(self):
1646 self.assertEqual(self._get_summary_line(dict.pop),
1647 "pop(self, key, default=<unrepresentable>, /) "
1648 "unbound builtins.dict method")
1649 _testcapi = import_helper.import_module("_testcapi")
1650 cls = _testcapi.DocStringUnrepresentableSignatureTest
1651 self.assertEqual(self._get_summary_line(cls.meth),
1652 "meth(self, /, a, b=<x>) unbound "
1653 "_testcapi.DocStringUnrepresentableSignatureTest method")
1654
1655 @support.cpython_only
1656 @requires_docstrings
1657 def test_bound_builtin_method_unrepresentable_default(self):
1658 self.assertEqual(self._get_summary_line({}.pop),
1659 "pop(key, default=<unrepresentable>, /) "
1660 "method of builtins.dict instance")
1661 _testcapi = import_helper.import_module("_testcapi")
1662 obj = _testcapi.DocStringUnrepresentableSignatureTest()
1663 self.assertEqual(self._get_summary_line(obj.meth),
1664 "meth(a, b=<x>) "
1665 "method of _testcapi.DocStringUnrepresentableSignatureTest instance")
1666
1667 @support.cpython_only
1668 @requires_docstrings
1669 def test_unbound_builtin_classmethod_unrepresentable_default(self):
1670 _testcapi = import_helper.import_module("_testcapi")
1671 cls = _testcapi.DocStringUnrepresentableSignatureTest
1672 descr = cls.__dict__['classmeth']
1673 self.assertEqual(self._get_summary_line(descr),
1674 "classmeth(type, /, a, b=<x>) unbound "
1675 "_testcapi.DocStringUnrepresentableSignatureTest method")
1676
1677 @support.cpython_only
1678 @requires_docstrings
1679 def test_bound_builtin_classmethod_unrepresentable_default(self):
1680 _testcapi = import_helper.import_module("_testcapi")
1681 cls = _testcapi.DocStringUnrepresentableSignatureTest
1682 self.assertEqual(self._get_summary_line(cls.classmeth),
1683 "classmeth(a, b=<x>) class method of "
1684 "_testcapi.DocStringUnrepresentableSignatureTest")
1685
1686 def test_overridden_text_signature(self):
1687 class C:
1688 def meth(*args, **kwargs):
1689 pass
1690 @classmethod
1691 def cmeth(*args, **kwargs):
1692 pass
1693 @staticmethod
1694 def smeth(*args, **kwargs):
1695 pass
1696 for text_signature, unbound, bound in [
1697 ("($slf)", "(slf, /)", "()"),
1698 ("($slf, /)", "(slf, /)", "()"),
1699 ("($slf, /, arg)", "(slf, /, arg)", "(arg)"),
1700 ("($slf, /, arg=<x>)", "(slf, /, arg=<x>)", "(arg=<x>)"),
1701 ("($slf, arg, /)", "(slf, arg, /)", "(arg, /)"),
1702 ("($slf, arg=<x>, /)", "(slf, arg=<x>, /)", "(arg=<x>, /)"),
1703 ("(/, slf, arg)", "(/, slf, arg)", "(/, slf, arg)"),
1704 ("(/, slf, arg=<x>)", "(/, slf, arg=<x>)", "(/, slf, arg=<x>)"),
1705 ("(slf, /, arg)", "(slf, /, arg)", "(arg)"),
1706 ("(slf, /, arg=<x>)", "(slf, /, arg=<x>)", "(arg=<x>)"),
1707 ("(slf, arg, /)", "(slf, arg, /)", "(arg, /)"),
1708 ("(slf, arg=<x>, /)", "(slf, arg=<x>, /)", "(arg=<x>, /)"),
1709 ]:
1710 with self.subTest(text_signature):
1711 C.meth.__text_signature__ = text_signature
1712 self.assertEqual(self._get_summary_line(C.meth),
1713 "meth" + unbound)
1714 self.assertEqual(self._get_summary_line(C().meth),
1715 "meth" + bound + " method of test.test_pydoc.test_pydoc.C instance")
1716 C.cmeth.__func__.__text_signature__ = text_signature
1717 self.assertEqual(self._get_summary_line(C.cmeth),
1718 "cmeth" + bound + " class method of test.test_pydoc.test_pydoc.C")
1719 C.smeth.__text_signature__ = text_signature
1720 self.assertEqual(self._get_summary_line(C.smeth),
1721 "smeth" + unbound)
1722
1723 @requires_docstrings
1724 def test_staticmethod(self):
1725 class X:
1726 @staticmethod
1727 def sm(x, y):
1728 '''A static method'''
1729 ...
1730 self.assertEqual(self._get_summary_lines(X.__dict__['sm']),
1731 'sm(x, y)\n'
1732 ' A static method\n')
1733 self.assertEqual(self._get_summary_lines(X.sm), """\
1734 sm(x, y)
1735 A static method
1736 """)
1737 self.assertIn("""
1738 | Static methods defined here:
1739 |
1740 | sm(x, y)
1741 | A static method
1742 """, pydoc.plain(pydoc.render_doc(X)))
1743
1744 @requires_docstrings
1745 def test_classmethod(self):
1746 class X:
1747 @classmethod
1748 def cm(cls, x):
1749 '''A class method'''
1750 ...
1751 self.assertEqual(self._get_summary_lines(X.__dict__['cm']),
1752 'cm(...)\n'
1753 ' A class method\n')
1754 self.assertEqual(self._get_summary_lines(X.cm), """\
1755 cm(x) class method of test.test_pydoc.test_pydoc.X
1756 A class method
1757 """)
1758 self.assertIn("""
1759 | Class methods defined here:
1760 |
1761 | cm(x)
1762 | A class method
1763 """, pydoc.plain(pydoc.render_doc(X)))
1764
1765 @requires_docstrings
1766 def test_getset_descriptor(self):
1767 # Currently these attributes are implemented as getset descriptors
1768 # in CPython.
1769 self.assertEqual(self._get_summary_line(int.numerator), "numerator")
1770 self.assertEqual(self._get_summary_line(float.real), "real")
1771 self.assertEqual(self._get_summary_line(Exception.args), "args")
1772 self.assertEqual(self._get_summary_line(memoryview.obj), "obj")
1773
1774 @requires_docstrings
1775 def test_member_descriptor(self):
1776 # Currently these attributes are implemented as member descriptors
1777 # in CPython.
1778 self.assertEqual(self._get_summary_line(complex.real), "real")
1779 self.assertEqual(self._get_summary_line(range.start), "start")
1780 self.assertEqual(self._get_summary_line(slice.start), "start")
1781 self.assertEqual(self._get_summary_line(property.fget), "fget")
1782 self.assertEqual(self._get_summary_line(StopIteration.value), "value")
1783
1784 @requires_docstrings
1785 def test_slot_descriptor(self):
1786 class Point:
1787 __slots__ = 'x', 'y'
1788 self.assertEqual(self._get_summary_line(Point.x), "x")
1789
1790 @requires_docstrings
1791 def test_dict_attr_descriptor(self):
1792 class NS:
1793 pass
1794 self.assertEqual(self._get_summary_line(NS.__dict__['__dict__']),
1795 "__dict__")
1796
1797 @requires_docstrings
1798 def test_structseq_member_descriptor(self):
1799 self.assertEqual(self._get_summary_line(type(sys.hash_info).width),
1800 "width")
1801 self.assertEqual(self._get_summary_line(type(sys.flags).debug),
1802 "debug")
1803 self.assertEqual(self._get_summary_line(type(sys.version_info).major),
1804 "major")
1805 self.assertEqual(self._get_summary_line(type(sys.float_info).max),
1806 "max")
1807
1808 @requires_docstrings
1809 def test_namedtuple_field_descriptor(self):
1810 Box = namedtuple('Box', ('width', 'height'))
1811 self.assertEqual(self._get_summary_lines(Box.width), """\
1812 Alias for field number 0
1813 """)
1814
1815 @requires_docstrings
1816 def test_property(self):
1817 self.assertEqual(self._get_summary_lines(Rect.area), """\
1818 area
1819 Area of the rect
1820 """)
1821 # inherits the docstring from Rect.area
1822 self.assertEqual(self._get_summary_lines(Square.area), """\
1823 area
1824 Area of the rect
1825 """)
1826 self.assertIn("""
1827 | area
1828 | Area of the rect
1829 """, pydoc.plain(pydoc.render_doc(Rect)))
1830
1831 @requires_docstrings
1832 def test_custom_non_data_descriptor(self):
1833 class Descr:
1834 def __get__(self, obj, cls):
1835 if obj is None:
1836 return self
1837 return 42
1838 class X:
1839 attr = Descr()
1840
1841 self.assertEqual(self._get_summary_lines(X.attr), f"""\
1842 <{__name__}.TestDescriptions.test_custom_non_data_descriptor.<locals>.Descr object>""")
1843
1844 X.attr.__doc__ = 'Custom descriptor'
1845 self.assertEqual(self._get_summary_lines(X.attr), f"""\
1846 <{__name__}.TestDescriptions.test_custom_non_data_descriptor.<locals>.Descr object>
1847 Custom descriptor
1848 """)
1849
1850 X.attr.__name__ = 'foo'
1851 self.assertEqual(self._get_summary_lines(X.attr), """\
1852 foo(...)
1853 Custom descriptor
1854 """)
1855
1856 @requires_docstrings
1857 def test_custom_data_descriptor(self):
1858 class Descr:
1859 def __get__(self, obj, cls):
1860 if obj is None:
1861 return self
1862 return 42
1863 def __set__(self, obj, cls):
1864 1/0
1865 class X:
1866 attr = Descr()
1867
1868 self.assertEqual(self._get_summary_lines(X.attr), "")
1869
1870 X.attr.__doc__ = 'Custom descriptor'
1871 self.assertEqual(self._get_summary_lines(X.attr), """\
1872 Custom descriptor
1873 """)
1874
1875 X.attr.__name__ = 'foo'
1876 self.assertEqual(self._get_summary_lines(X.attr), """\
1877 foo
1878 Custom descriptor
1879 """)
1880
1881 def test_async_annotation(self):
1882 async def coro_function(ign) -> int:
1883 return 1
1884
1885 text = pydoc.plain(pydoc.plaintext.document(coro_function))
1886 self.assertIn('async coro_function', text)
1887
1888 html = pydoc.HTMLDoc().document(coro_function)
1889 self.assertIn(
1890 'async <a name="-coro_function"><strong>coro_function',
1891 html)
1892
1893 def test_async_generator_annotation(self):
1894 async def an_async_generator():
1895 yield 1
1896
1897 text = pydoc.plain(pydoc.plaintext.document(an_async_generator))
1898 self.assertIn('async an_async_generator', text)
1899
1900 html = pydoc.HTMLDoc().document(an_async_generator)
1901 self.assertIn(
1902 'async <a name="-an_async_generator"><strong>an_async_generator',
1903 html)
1904
1905 @requires_docstrings
1906 def test_html_for_https_links(self):
1907 def a_fn_with_https_link():
1908 """a link https://localhost/"""
1909 pass
1910
1911 html = pydoc.HTMLDoc().document(a_fn_with_https_link)
1912 self.assertIn(
1913 '<a href="https://localhost/">https://localhost/</a>',
1914 html
1915 )
1916
1917 def test_module_none(self):
1918 # Issue #128772
1919 from test.test_pydoc import module_none
1920 pydoc.render_doc(module_none)
1921
1922
1923 class PydocFodderTest(unittest.TestCase):
1924 def tearDown(self):
1925 self.assertIs(sys.modules['pydoc'], pydoc)
1926
1927 def getsection(self, text, beginline, endline):
1928 lines = text.splitlines()
1929 beginindex, endindex = 0, None
1930 if beginline is not None:
1931 beginindex = lines.index(beginline)
1932 if endline is not None:
1933 endindex = lines.index(endline, beginindex)
1934 return lines[beginindex:endindex]
1935
1936 def test_text_doc_routines_in_class(self, cls=pydocfodder.B):
1937 doc = pydoc.TextDoc()
1938 result = doc.docclass(cls)
1939 result = clean_text(result)
1940 where = 'defined here' if cls is pydocfodder.B else 'inherited from B'
1941 lines = self.getsection(result, f' | Methods {where}:', ' | ' + '-'*70)
1942 self.assertIn(' | A_method_alias = A_method(self)', lines)
1943 self.assertIn(' | B_method_alias = B_method(self)', lines)
1944 self.assertIn(' | A_staticmethod(x, y) from test.test_pydoc.pydocfodder.A', lines)
1945 self.assertIn(' | A_staticmethod_alias = A_staticmethod(x, y)', lines)
1946 self.assertIn(' | global_func(x, y) from test.test_pydoc.pydocfodder', lines)
1947 self.assertIn(' | global_func_alias = global_func(x, y)', lines)
1948 self.assertIn(' | global_func2_alias = global_func2(x, y) from test.test_pydoc.pydocfodder', lines)
1949 if not support.MISSING_C_DOCSTRINGS:
1950 self.assertIn(' | count(self, value, /) from builtins.list', lines)
1951 self.assertIn(' | list_count = count(self, value, /)', lines)
1952 self.assertIn(' | __repr__(self, /) from builtins.object', lines)
1953 self.assertIn(' | object_repr = __repr__(self, /)', lines)
1954 else:
1955 self.assertIn(' | count(self, object, /) from builtins.list', lines)
1956 self.assertIn(' | list_count = count(self, object, /)', lines)
1957 self.assertIn(' | __repr__(...) from builtins.object', lines)
1958 self.assertIn(' | object_repr = __repr__(...)', lines)
1959
1960 lines = self.getsection(result, f' | Static methods {where}:', ' | ' + '-'*70)
1961 self.assertIn(' | A_classmethod_ref = A_classmethod(x) class method of test.test_pydoc.pydocfodder.A', lines)
1962 note = '' if cls is pydocfodder.B else ' class method of test.test_pydoc.pydocfodder.B'
1963 self.assertIn(' | B_classmethod_ref = B_classmethod(x)' + note, lines)
1964 self.assertIn(' | A_method_ref = A_method() method of test.test_pydoc.pydocfodder.A instance', lines)
1965 if not support.MISSING_C_DOCSTRINGS:
1966 self.assertIn(' | get(key, default=None, /) method of builtins.dict instance', lines)
1967 self.assertIn(' | dict_get = get(key, default=None, /) method of builtins.dict instance', lines)
1968 self.assertIn(' | sin(x, /)', lines)
1969 else:
1970 self.assertIn(' | get(...) method of builtins.dict instance', lines)
1971 self.assertIn(' | dict_get = get(...) method of builtins.dict instance', lines)
1972 self.assertIn(' | sin(object, /)', lines)
1973
1974 lines = self.getsection(result, f' | Class methods {where}:', ' | ' + '-'*70)
1975 self.assertIn(' | B_classmethod(x)', lines)
1976 self.assertIn(' | B_classmethod_alias = B_classmethod(x)', lines)
1977
1978 def test_html_doc_routines_in_class(self, cls=pydocfodder.B):
1979 doc = pydoc.HTMLDoc()
1980 result = doc.docclass(cls)
1981 result = html2text(result)
1982 where = 'defined here' if cls is pydocfodder.B else 'inherited from B'
1983 lines = self.getsection(result, f'Methods {where}:', '-'*70)
1984 self.assertIn('A_method_alias = A_method(self)', lines)
1985 self.assertIn('B_method_alias = B_method(self)', lines)
1986 self.assertIn('A_staticmethod(x, y) from test.test_pydoc.pydocfodder.A', lines)
1987 self.assertIn('A_staticmethod_alias = A_staticmethod(x, y)', lines)
1988 self.assertIn('global_func(x, y) from test.test_pydoc.pydocfodder', lines)
1989 self.assertIn('global_func_alias = global_func(x, y)', lines)
1990 self.assertIn('global_func2_alias = global_func2(x, y) from test.test_pydoc.pydocfodder', lines)
1991 if not support.MISSING_C_DOCSTRINGS:
1992 self.assertIn('count(self, value, /) from builtins.list', lines)
1993 self.assertIn('list_count = count(self, value, /)', lines)
1994 self.assertIn('__repr__(self, /) from builtins.object', lines)
1995 self.assertIn('object_repr = __repr__(self, /)', lines)
1996 else:
1997 self.assertIn('count(self, object, /) from builtins.list', lines)
1998 self.assertIn('list_count = count(self, object, /)', lines)
1999 self.assertIn('__repr__(...) from builtins.object', lines)
2000 self.assertIn('object_repr = __repr__(...)', lines)
2001
2002 lines = self.getsection(result, f'Static methods {where}:', '-'*70)
2003 self.assertIn('A_classmethod_ref = A_classmethod(x) class method of test.test_pydoc.pydocfodder.A', lines)
2004 note = '' if cls is pydocfodder.B else ' class method of test.test_pydoc.pydocfodder.B'
2005 self.assertIn('B_classmethod_ref = B_classmethod(x)' + note, lines)
2006 self.assertIn('A_method_ref = A_method() method of test.test_pydoc.pydocfodder.A instance', lines)
2007
2008 lines = self.getsection(result, f'Class methods {where}:', '-'*70)
2009 self.assertIn('B_classmethod(x)', lines)
2010 self.assertIn('B_classmethod_alias = B_classmethod(x)', lines)
2011
2012 def test_text_doc_inherited_routines_in_class(self):
2013 self.test_text_doc_routines_in_class(pydocfodder.D)
2014
2015 def test_html_doc_inherited_routines_in_class(self):
2016 self.test_html_doc_routines_in_class(pydocfodder.D)
2017
2018 def test_text_doc_routines_in_module(self):
2019 doc = pydoc.TextDoc()
2020 result = doc.docmodule(pydocfodder)
2021 result = clean_text(result)
2022 lines = self.getsection(result, 'FUNCTIONS', 'FILE')
2023 # function alias
2024 self.assertIn(' global_func_alias = global_func(x, y)', lines)
2025 self.assertIn(' A_staticmethod(x, y)', lines)
2026 self.assertIn(' A_staticmethod_alias = A_staticmethod(x, y)', lines)
2027 # bound class methods
2028 self.assertIn(' A_classmethod(x) class method of A', lines)
2029 self.assertIn(' A_classmethod2 = A_classmethod(x) class method of A', lines)
2030 self.assertIn(' A_classmethod3 = A_classmethod(x) class method of B', lines)
2031 # bound methods
2032 self.assertIn(' A_method() method of A instance', lines)
2033 self.assertIn(' A_method2 = A_method() method of A instance', lines)
2034 self.assertIn(' A_method3 = A_method() method of B instance', lines)
2035 self.assertIn(' A_staticmethod_ref = A_staticmethod(x, y)', lines)
2036 self.assertIn(' A_staticmethod_ref2 = A_staticmethod(y) method of B instance', lines)
2037 if not support.MISSING_C_DOCSTRINGS:
2038 self.assertIn(' get(key, default=None, /) method of builtins.dict instance', lines)
2039 self.assertIn(' dict_get = get(key, default=None, /) method of builtins.dict instance', lines)
2040 else:
2041 self.assertIn(' get(...) method of builtins.dict instance', lines)
2042 self.assertIn(' dict_get = get(...) method of builtins.dict instance', lines)
2043
2044 # unbound methods
2045 self.assertIn(' B_method(self)', lines)
2046 self.assertIn(' B_method2 = B_method(self)', lines)
2047 if not support.MISSING_C_DOCSTRINGS:
2048 self.assertIn(' count(self, value, /) unbound builtins.list method', lines)
2049 self.assertIn(' list_count = count(self, value, /) unbound builtins.list method', lines)
2050 self.assertIn(' __repr__(self, /) unbound builtins.object method', lines)
2051 self.assertIn(' object_repr = __repr__(self, /) unbound builtins.object method', lines)
2052 else:
2053 self.assertIn(' count(self, object, /) unbound builtins.list method', lines)
2054 self.assertIn(' list_count = count(self, object, /) unbound builtins.list method', lines)
2055 self.assertIn(' __repr__(...) unbound builtins.object method', lines)
2056 self.assertIn(' object_repr = __repr__(...) unbound builtins.object method', lines)
2057
2058 # builtin functions
2059 if not support.MISSING_C_DOCSTRINGS:
2060 self.assertIn(' sin(x, /)', lines)
2061 else:
2062 self.assertIn(' sin(object, /)', lines)
2063
2064 def test_html_doc_routines_in_module(self):
2065 doc = pydoc.HTMLDoc()
2066 result = doc.docmodule(pydocfodder)
2067 result = html2text(result)
2068 lines = self.getsection(result, ' Functions', None)
2069 # function alias
2070 self.assertIn(' global_func_alias = global_func(x, y)', lines)
2071 self.assertIn(' A_staticmethod(x, y)', lines)
2072 self.assertIn(' A_staticmethod_alias = A_staticmethod(x, y)', lines)
2073 # bound class methods
2074 self.assertIn('A_classmethod(x) class method of A', lines)
2075 self.assertIn(' A_classmethod2 = A_classmethod(x) class method of A', lines)
2076 self.assertIn(' A_classmethod3 = A_classmethod(x) class method of B', lines)
2077 # bound methods
2078 self.assertIn(' A_method() method of A instance', lines)
2079 self.assertIn(' A_method2 = A_method() method of A instance', lines)
2080 self.assertIn(' A_method3 = A_method() method of B instance', lines)
2081 self.assertIn(' A_staticmethod_ref = A_staticmethod(x, y)', lines)
2082 self.assertIn(' A_staticmethod_ref2 = A_staticmethod(y) method of B instance', lines)
2083 if not support.MISSING_C_DOCSTRINGS:
2084 self.assertIn(' get(key, default=None, /) method of builtins.dict instance', lines)
2085 self.assertIn(' dict_get = get(key, default=None, /) method of builtins.dict instance', lines)
2086 else:
2087 self.assertIn(' get(...) method of builtins.dict instance', lines)
2088 self.assertIn(' dict_get = get(...) method of builtins.dict instance', lines)
2089 # unbound methods
2090 self.assertIn(' B_method(self)', lines)
2091 self.assertIn(' B_method2 = B_method(self)', lines)
2092 if not support.MISSING_C_DOCSTRINGS:
2093 self.assertIn(' count(self, value, /) unbound builtins.list method', lines)
2094 self.assertIn(' list_count = count(self, value, /) unbound builtins.list method', lines)
2095 self.assertIn(' __repr__(self, /) unbound builtins.object method', lines)
2096 self.assertIn(' object_repr = __repr__(self, /) unbound builtins.object method', lines)
2097 else:
2098 self.assertIn(' count(self, object, /) unbound builtins.list method', lines)
2099 self.assertIn(' list_count = count(self, object, /) unbound builtins.list method', lines)
2100 self.assertIn(' __repr__(...) unbound builtins.object method', lines)
2101 self.assertIn(' object_repr = __repr__(...) unbound builtins.object method', lines)
2102
2103 # builtin functions
2104 if not support.MISSING_C_DOCSTRINGS:
2105 self.assertIn(' sin(x, /)', lines)
2106 else:
2107 self.assertIn(' sin(object, /)', lines)
2108
2109
2110 @unittest.skipIf(
2111 is_wasm32,
2112 "Socket server not available on Emscripten/WASI."
2113 )
2114 class PydocServerTest(unittest.TestCase):
2115 """Tests for pydoc._start_server"""
2116 def tearDown(self):
2117 self.assertIs(sys.modules['pydoc'], pydoc)
2118
2119 def test_server(self):
2120 # Minimal test that starts the server, checks that it works, then stops
2121 # it and checks its cleanup.
2122 def my_url_handler(url, content_type):
2123 text = 'the URL sent was: (%s, %s)' % (url, content_type)
2124 return text
2125
2126 serverthread = pydoc._start_server(
2127 my_url_handler,
2128 hostname='localhost',
2129 port=0,
2130 )
2131 self.assertEqual(serverthread.error, None)
2132 self.assertTrue(serverthread.serving)
2133 self.addCleanup(
2134 lambda: serverthread.stop() if serverthread.serving else None
2135 )
2136 self.assertIn('localhost', serverthread.url)
2137
2138 self.addCleanup(urlcleanup)
2139 self.assertEqual(
2140 b'the URL sent was: (/test, text/html)',
2141 urlopen(urllib.parse.urljoin(serverthread.url, '/test')).read(),
2142 )
2143 self.assertEqual(
2144 b'the URL sent was: (/test.css, text/css)',
2145 urlopen(urllib.parse.urljoin(serverthread.url, '/test.css')).read(),
2146 )
2147
2148 serverthread.stop()
2149 self.assertFalse(serverthread.serving)
2150 self.assertIsNone(serverthread.docserver)
2151 self.assertIsNone(serverthread.url)
2152
2153
2154 class PydocUrlHandlerTest(PydocBaseTest):
2155 """Tests for pydoc._url_handler"""
2156
2157 def test_content_type_err(self):
2158 f = pydoc._url_handler
2159 self.assertRaises(TypeError, f, 'A', '')
2160 self.assertRaises(TypeError, f, 'B', 'foobar')
2161
2162 def test_url_requests(self):
2163 # Test for the correct title in the html pages returned.
2164 # This tests the different parts of the URL handler without
2165 # getting too picky about the exact html.
2166 requests = [
2167 ("", "Pydoc: Index of Modules"),
2168 ("get?key=", "Pydoc: Index of Modules"),
2169 ("index", "Pydoc: Index of Modules"),
2170 ("topics", "Pydoc: Topics"),
2171 ("keywords", "Pydoc: Keywords"),
2172 ("pydoc", "Pydoc: module pydoc"),
2173 ("get?key=pydoc", "Pydoc: module pydoc"),
2174 ("search?key=pydoc", "Pydoc: Search Results"),
2175 ("topic?key=def", "Pydoc: KEYWORD def"),
2176 ("topic?key=STRINGS", "Pydoc: TOPIC STRINGS"),
2177 ("foobar", "Pydoc: Error - foobar"),
2178 ]
2179
2180 self.assertIs(sys.modules['pydoc'], pydoc)
2181 try:
2182 with self.restrict_walk_packages():
2183 for url, title in requests:
2184 self.call_url_handler(url, title)
2185 finally:
2186 # Some requests reload the module and change sys.modules.
2187 sys.modules['pydoc'] = pydoc
2188
2189
2190 class TestHelper(unittest.TestCase):
2191 def mock_interactive_session(self, inputs):
2192 """
2193 Given a list of inputs, run an interactive help session. Returns a string
2194 of what would be shown on screen.
2195 """
2196 input_iter = iter(inputs)
2197
2198 def mock_getline(prompt):
2199 output.write(prompt)
2200 next_input = next(input_iter)
2201 output.write(next_input + os.linesep)
2202 return next_input
2203
2204 with captured_stdout() as output:
2205 helper = pydoc.Helper(output=output)
2206 with unittest.mock.patch.object(helper, "getline", mock_getline):
2207 helper.interact()
2208
2209 # handle different line endings across platforms consistently
2210 return output.getvalue().strip().splitlines(keepends=False)
2211
2212 def test_keywords(self):
2213 self.assertEqual(sorted(pydoc.Helper.keywords),
2214 sorted(keyword.kwlist))
2215
2216 def test_interact_empty_line_continues(self):
2217 # gh-138568: test pressing Enter without input should continue in help session
2218 self.assertEqual(
2219 self.mock_interactive_session(["", " ", "quit"]),
2220 ["help> ", "help> ", "help> quit"],
2221 )
2222
2223 def test_interact_quit_commands_exit(self):
2224 quit_commands = ["quit", "q", "exit"]
2225 for quit_cmd in quit_commands:
2226 with self.subTest(quit_command=quit_cmd):
2227 self.assertEqual(
2228 self.mock_interactive_session([quit_cmd]),
2229 [f"help> {quit_cmd}"],
2230 )
2231
2232
2233 class PydocWithMetaClasses(unittest.TestCase):
2234 def tearDown(self):
2235 self.assertIs(sys.modules['pydoc'], pydoc)
2236
2237 @unittest.skipIf(hasattr(sys, 'gettrace') and sys.gettrace(),
2238 'trace function introduces __locals__ unexpectedly')
2239 @requires_docstrings
2240 def test_DynamicClassAttribute(self):
2241 class Meta(type):
2242 def __getattr__(self, name):
2243 if name == 'ham':
2244 return 'spam'
2245 return super().__getattr__(name)
2246 class DA(metaclass=Meta):
2247 @types.DynamicClassAttribute
2248 def ham(self):
2249 return 'eggs'
2250 expected_text_data_docstrings = tuple('\n | ' + s if s else ''
2251 for s in expected_data_docstrings)
2252 output = StringIO()
2253 helper = pydoc.Helper(output=output)
2254 helper(DA)
2255 expected_text = expected_dynamicattribute_pattern % (
2256 (__name__,) + expected_text_data_docstrings[:2])
2257 result = output.getvalue().strip()
2258 self.assertEqual(expected_text, result)
2259
2260 @unittest.skipIf(hasattr(sys, 'gettrace') and sys.gettrace(),
2261 'trace function introduces __locals__ unexpectedly')
2262 @requires_docstrings
2263 def test_virtualClassAttributeWithOneMeta(self):
2264 class Meta(type):
2265 def __dir__(cls):
2266 return ['__class__', '__module__', '__name__', 'LIFE']
2267 def __getattr__(self, name):
2268 if name =='LIFE':
2269 return 42
2270 return super().__getattr(name)
2271 class Class(metaclass=Meta):
2272 pass
2273 output = StringIO()
2274 helper = pydoc.Helper(output=output)
2275 helper(Class)
2276 expected_text = expected_virtualattribute_pattern1 % __name__
2277 result = output.getvalue().strip()
2278 self.assertEqual(expected_text, result)
2279
2280 @unittest.skipIf(hasattr(sys, 'gettrace') and sys.gettrace(),
2281 'trace function introduces __locals__ unexpectedly')
2282 @requires_docstrings
2283 def test_virtualClassAttributeWithTwoMeta(self):
2284 class Meta1(type):
2285 def __dir__(cls):
2286 return ['__class__', '__module__', '__name__', 'one']
2287 def __getattr__(self, name):
2288 if name =='one':
2289 return 1
2290 return super().__getattr__(name)
2291 class Meta2(type):
2292 def __dir__(cls):
2293 return ['__class__', '__module__', '__name__', 'two']
2294 def __getattr__(self, name):
2295 if name =='two':
2296 return 2
2297 return super().__getattr__(name)
2298 class Meta3(Meta1, Meta2):
2299 def __dir__(cls):
2300 return list(sorted(set(
2301 ['__class__', '__module__', '__name__', 'three'] +
2302 Meta1.__dir__(cls) + Meta2.__dir__(cls))))
2303 def __getattr__(self, name):
2304 if name =='three':
2305 return 3
2306 return super().__getattr__(name)
2307 class Class1(metaclass=Meta1):
2308 pass
2309 class Class2(Class1, metaclass=Meta3):
2310 pass
2311 output = StringIO()
2312 helper = pydoc.Helper(output=output)
2313 helper(Class1)
2314 expected_text1 = expected_virtualattribute_pattern2 % __name__
2315 result1 = output.getvalue().strip()
2316 self.assertEqual(expected_text1, result1)
2317 output = StringIO()
2318 helper = pydoc.Helper(output=output)
2319 helper(Class2)
2320 expected_text2 = expected_virtualattribute_pattern3 % __name__
2321 result2 = output.getvalue().strip()
2322 self.assertEqual(expected_text2, result2)
2323
2324 @unittest.skipIf(hasattr(sys, 'gettrace') and sys.gettrace(),
2325 'trace function introduces __locals__ unexpectedly')
2326 @requires_docstrings
2327 def test_buggy_dir(self):
2328 class M(type):
2329 def __dir__(cls):
2330 return ['__class__', '__name__', 'missing', 'here']
2331 class C(metaclass=M):
2332 here = 'present!'
2333 output = StringIO()
2334 helper = pydoc.Helper(output=output)
2335 helper(C)
2336 expected_text = expected_missingattribute_pattern % __name__
2337 result = output.getvalue().strip()
2338 self.assertEqual(expected_text, result)
2339
2340 def test_resolve_false(self):
2341 # Issue #23008: pydoc enum.{,Int}Enum failed
2342 # because bool(enum.Enum) is False.
2343 with captured_stdout() as help_io:
2344 pydoc.help('enum.Enum')
2345 helptext = help_io.getvalue()
2346 self.assertIn('class Enum', helptext)
2347
2348
2349 class TestInternalUtilities(unittest.TestCase):
2350
2351 def setUp(self):
2352 tmpdir = tempfile.TemporaryDirectory()
2353 self.argv0dir = tmpdir.name
2354 self.argv0 = os.path.join(tmpdir.name, "nonexistent")
2355 self.addCleanup(tmpdir.cleanup)
2356 self.abs_curdir = abs_curdir = os.getcwd()
2357 self.curdir_spellings = ["", os.curdir, abs_curdir]
2358
2359 def _get_revised_path(self, given_path, argv0=None):
2360 # Checking that pydoc.cli() actually calls pydoc._get_revised_path()
2361 # is handled via code review (at least for now).
2362 if argv0 is None:
2363 argv0 = self.argv0
2364 return pydoc._get_revised_path(given_path, argv0)
2365
2366 def _get_starting_path(self):
2367 # Get a copy of sys.path without the current directory.
2368 clean_path = sys.path.copy()
2369 for spelling in self.curdir_spellings:
2370 for __ in range(clean_path.count(spelling)):
2371 clean_path.remove(spelling)
2372 return clean_path
2373
2374 def test_sys_path_adjustment_adds_missing_curdir(self):
2375 clean_path = self._get_starting_path()
2376 expected_path = [self.abs_curdir] + clean_path
2377 self.assertEqual(self._get_revised_path(clean_path), expected_path)
2378
2379 def test_sys_path_adjustment_removes_argv0_dir(self):
2380 clean_path = self._get_starting_path()
2381 expected_path = [self.abs_curdir] + clean_path
2382 leading_argv0dir = [self.argv0dir] + clean_path
2383 self.assertEqual(self._get_revised_path(leading_argv0dir), expected_path)
2384 trailing_argv0dir = clean_path + [self.argv0dir]
2385 self.assertEqual(self._get_revised_path(trailing_argv0dir), expected_path)
2386
2387 def test_sys_path_adjustment_protects_pydoc_dir(self):
2388 def _get_revised_path(given_path):
2389 return self._get_revised_path(given_path, argv0=pydoc.__file__)
2390 clean_path = self._get_starting_path()
2391 leading_argv0dir = [self.argv0dir] + clean_path
2392 expected_path = [self.abs_curdir] + leading_argv0dir
2393 self.assertEqual(_get_revised_path(leading_argv0dir), expected_path)
2394 trailing_argv0dir = clean_path + [self.argv0dir]
2395 expected_path = [self.abs_curdir] + trailing_argv0dir
2396 self.assertEqual(_get_revised_path(trailing_argv0dir), expected_path)
2397
2398 def test_sys_path_adjustment_when_curdir_already_included(self):
2399 clean_path = self._get_starting_path()
2400 for spelling in self.curdir_spellings:
2401 with self.subTest(curdir_spelling=spelling):
2402 # If curdir is already present, no alterations are made at all
2403 leading_curdir = [spelling] + clean_path
2404 self.assertIsNone(self._get_revised_path(leading_curdir))
2405 trailing_curdir = clean_path + [spelling]
2406 self.assertIsNone(self._get_revised_path(trailing_curdir))
2407 leading_argv0dir = [self.argv0dir] + leading_curdir
2408 self.assertIsNone(self._get_revised_path(leading_argv0dir))
2409 trailing_argv0dir = trailing_curdir + [self.argv0dir]
2410 self.assertIsNone(self._get_revised_path(trailing_argv0dir))
2411
2412
2413 def setUpModule():
2414 thread_info = threading_helper.threading_setup()
2415 unittest.addModuleCleanup(threading_helper.threading_cleanup, *thread_info)
2416 unittest.addModuleCleanup(reap_children)
2417
2418
2419 if __name__ == "__main__":
2420 unittest.main()