2a37f8f55b
Previously, it was hard to tell whether a function should be awaited. It was also incorrect (per PEP 484) to put this in the type hint for coroutine functions. Added this info to the output of builtins.help and pydoc. https://bugs.python.org/issue36045
1582 lines
57 KiB
Python
1582 lines
57 KiB
Python
import os
|
|
import sys
|
|
import contextlib
|
|
import importlib.util
|
|
import inspect
|
|
import pydoc
|
|
import py_compile
|
|
import keyword
|
|
import _pickle
|
|
import pkgutil
|
|
import re
|
|
import stat
|
|
import string
|
|
import tempfile
|
|
import test.support
|
|
import time
|
|
import types
|
|
import typing
|
|
import unittest
|
|
import urllib.parse
|
|
import xml.etree
|
|
import xml.etree.ElementTree
|
|
import textwrap
|
|
import threading
|
|
from io import StringIO
|
|
from collections import namedtuple
|
|
from test.support.script_helper import assert_python_ok
|
|
from test.support import (
|
|
TESTFN, rmtree,
|
|
reap_children, reap_threads, captured_output, captured_stdout,
|
|
captured_stderr, unlink, requires_docstrings
|
|
)
|
|
from test import pydoc_mod
|
|
|
|
|
|
class nonascii:
|
|
'Це не латиниця'
|
|
pass
|
|
|
|
if test.support.HAVE_DOCSTRINGS:
|
|
expected_data_docstrings = (
|
|
'dictionary for instance variables (if defined)',
|
|
'list of weak references to the object (if defined)',
|
|
) * 2
|
|
else:
|
|
expected_data_docstrings = ('', '', '', '')
|
|
|
|
expected_text_pattern = """
|
|
NAME
|
|
test.pydoc_mod - This is a test module for test_pydoc
|
|
%s
|
|
CLASSES
|
|
builtins.object
|
|
A
|
|
B
|
|
C
|
|
\x20\x20\x20\x20
|
|
class A(builtins.object)
|
|
| Hello and goodbye
|
|
|\x20\x20
|
|
| Methods defined here:
|
|
|\x20\x20
|
|
| __init__()
|
|
| Wow, I have no function!
|
|
|\x20\x20
|
|
| ----------------------------------------------------------------------
|
|
| Data descriptors defined here:
|
|
|\x20\x20
|
|
| __dict__%s
|
|
|\x20\x20
|
|
| __weakref__%s
|
|
\x20\x20\x20\x20
|
|
class B(builtins.object)
|
|
| Data descriptors defined here:
|
|
|\x20\x20
|
|
| __dict__%s
|
|
|\x20\x20
|
|
| __weakref__%s
|
|
|\x20\x20
|
|
| ----------------------------------------------------------------------
|
|
| Data and other attributes defined here:
|
|
|\x20\x20
|
|
| NO_MEANING = 'eggs'
|
|
|\x20\x20
|
|
| __annotations__ = {'NO_MEANING': <class 'str'>}
|
|
\x20\x20\x20\x20
|
|
class C(builtins.object)
|
|
| Methods defined here:
|
|
|\x20\x20
|
|
| get_answer(self)
|
|
| Return say_no()
|
|
|\x20\x20
|
|
| is_it_true(self)
|
|
| Return self.get_answer()
|
|
|\x20\x20
|
|
| say_no(self)
|
|
|\x20\x20
|
|
| ----------------------------------------------------------------------
|
|
| Data descriptors defined here:
|
|
|\x20\x20
|
|
| __dict__
|
|
| dictionary for instance variables (if defined)
|
|
|\x20\x20
|
|
| __weakref__
|
|
| list of weak references to the object (if defined)
|
|
|
|
FUNCTIONS
|
|
doc_func()
|
|
This function solves all of the world's problems:
|
|
hunger
|
|
lack of Python
|
|
war
|
|
\x20\x20\x20\x20
|
|
nodoc_func()
|
|
|
|
DATA
|
|
__xyz__ = 'X, Y and Z'
|
|
|
|
VERSION
|
|
1.2.3.4
|
|
|
|
AUTHOR
|
|
Benjamin Peterson
|
|
|
|
CREDITS
|
|
Nobody
|
|
|
|
FILE
|
|
%s
|
|
""".strip()
|
|
|
|
expected_text_data_docstrings = tuple('\n | ' + s if s else ''
|
|
for s in expected_data_docstrings)
|
|
|
|
expected_html_pattern = """
|
|
<table width="100%%" cellspacing=0 cellpadding=2 border=0 summary="heading">
|
|
<tr bgcolor="#7799ee">
|
|
<td valign=bottom> <br>
|
|
<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
|
|
><td align=right valign=bottom
|
|
><font color="#ffffff" face="helvetica, arial"><a href=".">index</a><br><a href="file:%s">%s</a>%s</font></td></tr></table>
|
|
<p><tt>This is a test module for test_pydoc</tt></p>
|
|
<p>
|
|
<table width="100%%" cellspacing=0 cellpadding=2 border=0 summary="section">
|
|
<tr bgcolor="#ee77aa">
|
|
<td colspan=3 valign=bottom> <br>
|
|
<font color="#ffffff" face="helvetica, arial"><big><strong>Classes</strong></big></font></td></tr>
|
|
\x20\x20\x20\x20
|
|
<tr><td bgcolor="#ee77aa"><tt> </tt></td><td> </td>
|
|
<td width="100%%"><dl>
|
|
<dt><font face="helvetica, arial"><a href="builtins.html#object">builtins.object</a>
|
|
</font></dt><dd>
|
|
<dl>
|
|
<dt><font face="helvetica, arial"><a href="test.pydoc_mod.html#A">A</a>
|
|
</font></dt><dt><font face="helvetica, arial"><a href="test.pydoc_mod.html#B">B</a>
|
|
</font></dt><dt><font face="helvetica, arial"><a href="test.pydoc_mod.html#C">C</a>
|
|
</font></dt></dl>
|
|
</dd>
|
|
</dl>
|
|
<p>
|
|
<table width="100%%" cellspacing=0 cellpadding=2 border=0 summary="section">
|
|
<tr bgcolor="#ffc8d8">
|
|
<td colspan=3 valign=bottom> <br>
|
|
<font color="#000000" face="helvetica, arial"><a name="A">class <strong>A</strong></a>(<a href="builtins.html#object">builtins.object</a>)</font></td></tr>
|
|
\x20\x20\x20\x20
|
|
<tr bgcolor="#ffc8d8"><td rowspan=2><tt> </tt></td>
|
|
<td colspan=2><tt>Hello and goodbye<br> </tt></td></tr>
|
|
<tr><td> </td>
|
|
<td width="100%%">Methods defined here:<br>
|
|
<dl><dt><a name="A-__init__"><strong>__init__</strong></a>()</dt><dd><tt>Wow, I have no function!</tt></dd></dl>
|
|
|
|
<hr>
|
|
Data descriptors defined here:<br>
|
|
<dl><dt><strong>__dict__</strong></dt>
|
|
<dd><tt>%s</tt></dd>
|
|
</dl>
|
|
<dl><dt><strong>__weakref__</strong></dt>
|
|
<dd><tt>%s</tt></dd>
|
|
</dl>
|
|
</td></tr></table> <p>
|
|
<table width="100%%" cellspacing=0 cellpadding=2 border=0 summary="section">
|
|
<tr bgcolor="#ffc8d8">
|
|
<td colspan=3 valign=bottom> <br>
|
|
<font color="#000000" face="helvetica, arial"><a name="B">class <strong>B</strong></a>(<a href="builtins.html#object">builtins.object</a>)</font></td></tr>
|
|
\x20\x20\x20\x20
|
|
<tr><td bgcolor="#ffc8d8"><tt> </tt></td><td> </td>
|
|
<td width="100%%">Data descriptors defined here:<br>
|
|
<dl><dt><strong>__dict__</strong></dt>
|
|
<dd><tt>%s</tt></dd>
|
|
</dl>
|
|
<dl><dt><strong>__weakref__</strong></dt>
|
|
<dd><tt>%s</tt></dd>
|
|
</dl>
|
|
<hr>
|
|
Data and other attributes defined here:<br>
|
|
<dl><dt><strong>NO_MEANING</strong> = 'eggs'</dl>
|
|
|
|
<dl><dt><strong>__annotations__</strong> = {'NO_MEANING': <class 'str'>}</dl>
|
|
|
|
</td></tr></table> <p>
|
|
<table width="100%%" cellspacing=0 cellpadding=2 border=0 summary="section">
|
|
<tr bgcolor="#ffc8d8">
|
|
<td colspan=3 valign=bottom> <br>
|
|
<font color="#000000" face="helvetica, arial"><a name="C">class <strong>C</strong></a>(<a href="builtins.html#object">builtins.object</a>)</font></td></tr>
|
|
\x20\x20\x20\x20
|
|
<tr><td bgcolor="#ffc8d8"><tt> </tt></td><td> </td>
|
|
<td width="100%%">Methods defined here:<br>
|
|
<dl><dt><a name="C-get_answer"><strong>get_answer</strong></a>(self)</dt><dd><tt>Return <a href="#C-say_no">say_no</a>()</tt></dd></dl>
|
|
|
|
<dl><dt><a name="C-is_it_true"><strong>is_it_true</strong></a>(self)</dt><dd><tt>Return self.<a href="#C-get_answer">get_answer</a>()</tt></dd></dl>
|
|
|
|
<dl><dt><a name="C-say_no"><strong>say_no</strong></a>(self)</dt></dl>
|
|
|
|
<hr>
|
|
Data descriptors defined here:<br>
|
|
<dl><dt><strong>__dict__</strong></dt>
|
|
<dd><tt>dictionary for instance variables (if defined)</tt></dd>
|
|
</dl>
|
|
<dl><dt><strong>__weakref__</strong></dt>
|
|
<dd><tt>list of weak references to the object (if defined)</tt></dd>
|
|
</dl>
|
|
</td></tr></table></td></tr></table><p>
|
|
<table width="100%%" cellspacing=0 cellpadding=2 border=0 summary="section">
|
|
<tr bgcolor="#eeaa77">
|
|
<td colspan=3 valign=bottom> <br>
|
|
<font color="#ffffff" face="helvetica, arial"><big><strong>Functions</strong></big></font></td></tr>
|
|
\x20\x20\x20\x20
|
|
<tr><td bgcolor="#eeaa77"><tt> </tt></td><td> </td>
|
|
<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>
|
|
hunger<br>
|
|
lack of Python<br>
|
|
war</tt></dd></dl>
|
|
<dl><dt><a name="-nodoc_func"><strong>nodoc_func</strong></a>()</dt></dl>
|
|
</td></tr></table><p>
|
|
<table width="100%%" cellspacing=0 cellpadding=2 border=0 summary="section">
|
|
<tr bgcolor="#55aa55">
|
|
<td colspan=3 valign=bottom> <br>
|
|
<font color="#ffffff" face="helvetica, arial"><big><strong>Data</strong></big></font></td></tr>
|
|
\x20\x20\x20\x20
|
|
<tr><td bgcolor="#55aa55"><tt> </tt></td><td> </td>
|
|
<td width="100%%"><strong>__xyz__</strong> = 'X, Y and Z'</td></tr></table><p>
|
|
<table width="100%%" cellspacing=0 cellpadding=2 border=0 summary="section">
|
|
<tr bgcolor="#7799ee">
|
|
<td colspan=3 valign=bottom> <br>
|
|
<font color="#ffffff" face="helvetica, arial"><big><strong>Author</strong></big></font></td></tr>
|
|
\x20\x20\x20\x20
|
|
<tr><td bgcolor="#7799ee"><tt> </tt></td><td> </td>
|
|
<td width="100%%">Benjamin Peterson</td></tr></table><p>
|
|
<table width="100%%" cellspacing=0 cellpadding=2 border=0 summary="section">
|
|
<tr bgcolor="#7799ee">
|
|
<td colspan=3 valign=bottom> <br>
|
|
<font color="#ffffff" face="helvetica, arial"><big><strong>Credits</strong></big></font></td></tr>
|
|
\x20\x20\x20\x20
|
|
<tr><td bgcolor="#7799ee"><tt> </tt></td><td> </td>
|
|
<td width="100%%">Nobody</td></tr></table>
|
|
""".strip() # ' <- emacs turd
|
|
|
|
expected_html_data_docstrings = tuple(s.replace(' ', ' ')
|
|
for s in expected_data_docstrings)
|
|
|
|
# output pattern for missing module
|
|
missing_pattern = '''\
|
|
No Python documentation found for %r.
|
|
Use help() to get the interactive help utility.
|
|
Use help(str) for help on the str class.'''.replace('\n', os.linesep)
|
|
|
|
# output pattern for module with bad imports
|
|
badimport_pattern = "problem in %s - ModuleNotFoundError: No module named %r"
|
|
|
|
expected_dynamicattribute_pattern = """
|
|
Help on class DA in module %s:
|
|
|
|
class DA(builtins.object)
|
|
| Data descriptors defined here:
|
|
|\x20\x20
|
|
| __dict__%s
|
|
|\x20\x20
|
|
| __weakref__%s
|
|
|\x20\x20
|
|
| ham
|
|
|\x20\x20
|
|
| ----------------------------------------------------------------------
|
|
| Data and other attributes inherited from Meta:
|
|
|\x20\x20
|
|
| ham = 'spam'
|
|
""".strip()
|
|
|
|
expected_virtualattribute_pattern1 = """
|
|
Help on class Class in module %s:
|
|
|
|
class Class(builtins.object)
|
|
| Data and other attributes inherited from Meta:
|
|
|\x20\x20
|
|
| LIFE = 42
|
|
""".strip()
|
|
|
|
expected_virtualattribute_pattern2 = """
|
|
Help on class Class1 in module %s:
|
|
|
|
class Class1(builtins.object)
|
|
| Data and other attributes inherited from Meta1:
|
|
|\x20\x20
|
|
| one = 1
|
|
""".strip()
|
|
|
|
expected_virtualattribute_pattern3 = """
|
|
Help on class Class2 in module %s:
|
|
|
|
class Class2(Class1)
|
|
| Method resolution order:
|
|
| Class2
|
|
| Class1
|
|
| builtins.object
|
|
|\x20\x20
|
|
| Data and other attributes inherited from Meta1:
|
|
|\x20\x20
|
|
| one = 1
|
|
|\x20\x20
|
|
| ----------------------------------------------------------------------
|
|
| Data and other attributes inherited from Meta3:
|
|
|\x20\x20
|
|
| three = 3
|
|
|\x20\x20
|
|
| ----------------------------------------------------------------------
|
|
| Data and other attributes inherited from Meta2:
|
|
|\x20\x20
|
|
| two = 2
|
|
""".strip()
|
|
|
|
expected_missingattribute_pattern = """
|
|
Help on class C in module %s:
|
|
|
|
class C(builtins.object)
|
|
| Data and other attributes defined here:
|
|
|\x20\x20
|
|
| here = 'present!'
|
|
""".strip()
|
|
|
|
def run_pydoc(module_name, *args, **env):
|
|
"""
|
|
Runs pydoc on the specified module. Returns the stripped
|
|
output of pydoc.
|
|
"""
|
|
args = args + (module_name,)
|
|
# do not write bytecode files to avoid caching errors
|
|
rc, out, err = assert_python_ok('-B', pydoc.__file__, *args, **env)
|
|
return out.strip()
|
|
|
|
def get_pydoc_html(module):
|
|
"Returns pydoc generated output as html"
|
|
doc = pydoc.HTMLDoc()
|
|
output = doc.docmodule(module)
|
|
loc = doc.getdocloc(pydoc_mod) or ""
|
|
if loc:
|
|
loc = "<br><a href=\"" + loc + "\">Module Docs</a>"
|
|
return output.strip(), loc
|
|
|
|
def get_pydoc_link(module):
|
|
"Returns a documentation web link of a module"
|
|
abspath = os.path.abspath
|
|
dirname = os.path.dirname
|
|
basedir = dirname(dirname(abspath(__file__)))
|
|
doc = pydoc.TextDoc()
|
|
loc = doc.getdocloc(module, basedir=basedir)
|
|
return loc
|
|
|
|
def get_pydoc_text(module):
|
|
"Returns pydoc generated output as text"
|
|
doc = pydoc.TextDoc()
|
|
loc = doc.getdocloc(pydoc_mod) or ""
|
|
if loc:
|
|
loc = "\nMODULE DOCS\n " + loc + "\n"
|
|
|
|
output = doc.docmodule(module)
|
|
|
|
# clean up the extra text formatting that pydoc performs
|
|
patt = re.compile('\b.')
|
|
output = patt.sub('', output)
|
|
return output.strip(), loc
|
|
|
|
def get_html_title(text):
|
|
# Bit of hack, but good enough for test purposes
|
|
header, _, _ = text.partition("</head>")
|
|
_, _, title = header.partition("<title>")
|
|
title, _, _ = title.partition("</title>")
|
|
return title
|
|
|
|
|
|
class PydocBaseTest(unittest.TestCase):
|
|
|
|
def _restricted_walk_packages(self, walk_packages, path=None):
|
|
"""
|
|
A version of pkgutil.walk_packages() that will restrict itself to
|
|
a given path.
|
|
"""
|
|
default_path = path or [os.path.dirname(__file__)]
|
|
def wrapper(path=None, prefix='', onerror=None):
|
|
return walk_packages(path or default_path, prefix, onerror)
|
|
return wrapper
|
|
|
|
@contextlib.contextmanager
|
|
def restrict_walk_packages(self, path=None):
|
|
walk_packages = pkgutil.walk_packages
|
|
pkgutil.walk_packages = self._restricted_walk_packages(walk_packages,
|
|
path)
|
|
try:
|
|
yield
|
|
finally:
|
|
pkgutil.walk_packages = walk_packages
|
|
|
|
def call_url_handler(self, url, expected_title):
|
|
text = pydoc._url_handler(url, "text/html")
|
|
result = get_html_title(text)
|
|
# Check the title to ensure an unexpected error page was not returned
|
|
self.assertEqual(result, expected_title, text)
|
|
return text
|
|
|
|
|
|
class PydocDocTest(unittest.TestCase):
|
|
maxDiff = None
|
|
|
|
@unittest.skipIf(sys.flags.optimize >= 2,
|
|
"Docstrings are omitted with -O2 and above")
|
|
@unittest.skipIf(hasattr(sys, 'gettrace') and sys.gettrace(),
|
|
'trace function introduces __locals__ unexpectedly')
|
|
@requires_docstrings
|
|
def test_html_doc(self):
|
|
result, doc_loc = get_pydoc_html(pydoc_mod)
|
|
mod_file = inspect.getabsfile(pydoc_mod)
|
|
mod_url = urllib.parse.quote(mod_file)
|
|
expected_html = expected_html_pattern % (
|
|
(mod_url, mod_file, doc_loc) +
|
|
expected_html_data_docstrings)
|
|
self.assertEqual(result, expected_html)
|
|
|
|
@unittest.skipIf(sys.flags.optimize >= 2,
|
|
"Docstrings are omitted with -O2 and above")
|
|
@unittest.skipIf(hasattr(sys, 'gettrace') and sys.gettrace(),
|
|
'trace function introduces __locals__ unexpectedly')
|
|
@requires_docstrings
|
|
def test_text_doc(self):
|
|
result, doc_loc = get_pydoc_text(pydoc_mod)
|
|
expected_text = expected_text_pattern % (
|
|
(doc_loc,) +
|
|
expected_text_data_docstrings +
|
|
(inspect.getabsfile(pydoc_mod),))
|
|
self.assertEqual(expected_text, result)
|
|
|
|
def test_text_enum_member_with_value_zero(self):
|
|
# Test issue #20654 to ensure enum member with value 0 can be
|
|
# displayed. It used to throw KeyError: 'zero'.
|
|
import enum
|
|
class BinaryInteger(enum.IntEnum):
|
|
zero = 0
|
|
one = 1
|
|
doc = pydoc.render_doc(BinaryInteger)
|
|
self.assertIn('<BinaryInteger.zero: 0>', doc)
|
|
|
|
def test_mixed_case_module_names_are_lower_cased(self):
|
|
# issue16484
|
|
doc_link = get_pydoc_link(xml.etree.ElementTree)
|
|
self.assertIn('xml.etree.elementtree', doc_link)
|
|
|
|
def test_issue8225(self):
|
|
# Test issue8225 to ensure no doc link appears for xml.etree
|
|
result, doc_loc = get_pydoc_text(xml.etree)
|
|
self.assertEqual(doc_loc, "", "MODULE DOCS incorrectly includes a link")
|
|
|
|
def test_getpager_with_stdin_none(self):
|
|
previous_stdin = sys.stdin
|
|
try:
|
|
sys.stdin = None
|
|
pydoc.getpager() # Shouldn't fail.
|
|
finally:
|
|
sys.stdin = previous_stdin
|
|
|
|
def test_non_str_name(self):
|
|
# issue14638
|
|
# Treat illegal (non-str) name like no name
|
|
class A:
|
|
__name__ = 42
|
|
class B:
|
|
pass
|
|
adoc = pydoc.render_doc(A())
|
|
bdoc = pydoc.render_doc(B())
|
|
self.assertEqual(adoc.replace("A", "B"), bdoc)
|
|
|
|
def test_not_here(self):
|
|
missing_module = "test.i_am_not_here"
|
|
result = str(run_pydoc(missing_module), 'ascii')
|
|
expected = missing_pattern % missing_module
|
|
self.assertEqual(expected, result,
|
|
"documentation for missing module found")
|
|
|
|
@unittest.skipIf(sys.flags.optimize >= 2,
|
|
'Docstrings are omitted with -OO and above')
|
|
def test_not_ascii(self):
|
|
result = run_pydoc('test.test_pydoc.nonascii', PYTHONIOENCODING='ascii')
|
|
encoded = nonascii.__doc__.encode('ascii', 'backslashreplace')
|
|
self.assertIn(encoded, result)
|
|
|
|
def test_input_strip(self):
|
|
missing_module = " test.i_am_not_here "
|
|
result = str(run_pydoc(missing_module), 'ascii')
|
|
expected = missing_pattern % missing_module.strip()
|
|
self.assertEqual(expected, result)
|
|
|
|
def test_stripid(self):
|
|
# test with strings, other implementations might have different repr()
|
|
stripid = pydoc.stripid
|
|
# strip the id
|
|
self.assertEqual(stripid('<function stripid at 0x88dcee4>'),
|
|
'<function stripid>')
|
|
self.assertEqual(stripid('<function stripid at 0x01F65390>'),
|
|
'<function stripid>')
|
|
# nothing to strip, return the same text
|
|
self.assertEqual(stripid('42'), '42')
|
|
self.assertEqual(stripid("<type 'exceptions.Exception'>"),
|
|
"<type 'exceptions.Exception'>")
|
|
|
|
def test_builtin_with_more_than_four_children(self):
|
|
"""Tests help on builtin object which have more than four child classes.
|
|
|
|
When running help() on a builtin class which has child classes, it
|
|
should contain a "Built-in subclasses" section and only 4 classes
|
|
should be displayed with a hint on how many more subclasses are present.
|
|
For example:
|
|
|
|
>>> help(object)
|
|
Help on class object in module builtins:
|
|
|
|
class object
|
|
| The most base type
|
|
|
|
|
| Built-in subclasses:
|
|
| async_generator
|
|
| BaseException
|
|
| builtin_function_or_method
|
|
| bytearray
|
|
| ... and 82 other subclasses
|
|
"""
|
|
doc = pydoc.TextDoc()
|
|
text = doc.docclass(object)
|
|
snip = (" | Built-in subclasses:\n"
|
|
" | async_generator\n"
|
|
" | BaseException\n"
|
|
" | builtin_function_or_method\n"
|
|
" | bytearray\n"
|
|
" | ... and \\d+ other subclasses")
|
|
self.assertRegex(text, snip)
|
|
|
|
def test_builtin_with_child(self):
|
|
"""Tests help on builtin object which have only child classes.
|
|
|
|
When running help() on a builtin class which has child classes, it
|
|
should contain a "Built-in subclasses" section. For example:
|
|
|
|
>>> help(ArithmeticError)
|
|
Help on class ArithmeticError in module builtins:
|
|
|
|
class ArithmeticError(Exception)
|
|
| Base class for arithmetic errors.
|
|
|
|
|
...
|
|
|
|
|
| Built-in subclasses:
|
|
| FloatingPointError
|
|
| OverflowError
|
|
| ZeroDivisionError
|
|
"""
|
|
doc = pydoc.TextDoc()
|
|
text = doc.docclass(ArithmeticError)
|
|
snip = (" | Built-in subclasses:\n"
|
|
" | FloatingPointError\n"
|
|
" | OverflowError\n"
|
|
" | ZeroDivisionError")
|
|
self.assertIn(snip, text)
|
|
|
|
def test_builtin_with_grandchild(self):
|
|
"""Tests help on builtin classes which have grandchild classes.
|
|
|
|
When running help() on a builtin class which has child classes, it
|
|
should contain a "Built-in subclasses" section. However, if it also has
|
|
grandchildren, these should not show up on the subclasses section.
|
|
For example:
|
|
|
|
>>> help(Exception)
|
|
Help on class Exception in module builtins:
|
|
|
|
class Exception(BaseException)
|
|
| Common base class for all non-exit exceptions.
|
|
|
|
|
...
|
|
|
|
|
| Built-in subclasses:
|
|
| ArithmeticError
|
|
| AssertionError
|
|
| AttributeError
|
|
...
|
|
"""
|
|
doc = pydoc.TextDoc()
|
|
text = doc.docclass(Exception)
|
|
snip = (" | Built-in subclasses:\n"
|
|
" | ArithmeticError\n"
|
|
" | AssertionError\n"
|
|
" | AttributeError")
|
|
self.assertIn(snip, text)
|
|
# Testing that the grandchild ZeroDivisionError does not show up
|
|
self.assertNotIn('ZeroDivisionError', text)
|
|
|
|
def test_builtin_no_child(self):
|
|
"""Tests help on builtin object which have no child classes.
|
|
|
|
When running help() on a builtin class which has no child classes, it
|
|
should not contain any "Built-in subclasses" section. For example:
|
|
|
|
>>> help(ZeroDivisionError)
|
|
|
|
Help on class ZeroDivisionError in module builtins:
|
|
|
|
class ZeroDivisionError(ArithmeticError)
|
|
| Second argument to a division or modulo operation was zero.
|
|
|
|
|
| Method resolution order:
|
|
| ZeroDivisionError
|
|
| ArithmeticError
|
|
| Exception
|
|
| BaseException
|
|
| object
|
|
|
|
|
| Methods defined here:
|
|
...
|
|
"""
|
|
doc = pydoc.TextDoc()
|
|
text = doc.docclass(ZeroDivisionError)
|
|
# Testing that the subclasses section does not appear
|
|
self.assertNotIn('Built-in subclasses', text)
|
|
|
|
def test_builtin_on_metaclasses(self):
|
|
"""Tests help on metaclasses.
|
|
|
|
When running help() on a metaclasses such as type, it
|
|
should not contain any "Built-in subclasses" section.
|
|
"""
|
|
doc = pydoc.TextDoc()
|
|
text = doc.docclass(type)
|
|
# Testing that the subclasses section does not appear
|
|
self.assertNotIn('Built-in subclasses', text)
|
|
|
|
@unittest.skipIf(sys.flags.optimize >= 2,
|
|
'Docstrings are omitted with -O2 and above')
|
|
@unittest.skipIf(hasattr(sys, 'gettrace') and sys.gettrace(),
|
|
'trace function introduces __locals__ unexpectedly')
|
|
@requires_docstrings
|
|
def test_help_output_redirect(self):
|
|
# issue 940286, if output is set in Helper, then all output from
|
|
# Helper.help should be redirected
|
|
old_pattern = expected_text_pattern
|
|
getpager_old = pydoc.getpager
|
|
getpager_new = lambda: (lambda x: x)
|
|
self.maxDiff = None
|
|
|
|
buf = StringIO()
|
|
helper = pydoc.Helper(output=buf)
|
|
unused, doc_loc = get_pydoc_text(pydoc_mod)
|
|
module = "test.pydoc_mod"
|
|
help_header = """
|
|
Help on module test.pydoc_mod in test:
|
|
|
|
""".lstrip()
|
|
help_header = textwrap.dedent(help_header)
|
|
expected_help_pattern = help_header + expected_text_pattern
|
|
|
|
pydoc.getpager = getpager_new
|
|
try:
|
|
with captured_output('stdout') as output, \
|
|
captured_output('stderr') as err:
|
|
helper.help(module)
|
|
result = buf.getvalue().strip()
|
|
expected_text = expected_help_pattern % (
|
|
(doc_loc,) +
|
|
expected_text_data_docstrings +
|
|
(inspect.getabsfile(pydoc_mod),))
|
|
self.assertEqual('', output.getvalue())
|
|
self.assertEqual('', err.getvalue())
|
|
self.assertEqual(expected_text, result)
|
|
finally:
|
|
pydoc.getpager = getpager_old
|
|
|
|
def test_namedtuple_fields(self):
|
|
Person = namedtuple('Person', ['nickname', 'firstname'])
|
|
with captured_stdout() as help_io:
|
|
pydoc.help(Person)
|
|
helptext = help_io.getvalue()
|
|
self.assertIn("nickname", helptext)
|
|
self.assertIn("firstname", helptext)
|
|
self.assertIn("Alias for field number 0", helptext)
|
|
self.assertIn("Alias for field number 1", helptext)
|
|
|
|
def test_namedtuple_public_underscore(self):
|
|
NT = namedtuple('NT', ['abc', 'def'], rename=True)
|
|
with captured_stdout() as help_io:
|
|
pydoc.help(NT)
|
|
helptext = help_io.getvalue()
|
|
self.assertIn('_1', helptext)
|
|
self.assertIn('_replace', helptext)
|
|
self.assertIn('_asdict', helptext)
|
|
|
|
def test_synopsis(self):
|
|
self.addCleanup(unlink, TESTFN)
|
|
for encoding in ('ISO-8859-1', 'UTF-8'):
|
|
with open(TESTFN, 'w', encoding=encoding) as script:
|
|
if encoding != 'UTF-8':
|
|
print('#coding: {}'.format(encoding), file=script)
|
|
print('"""line 1: h\xe9', file=script)
|
|
print('line 2: hi"""', file=script)
|
|
synopsis = pydoc.synopsis(TESTFN, {})
|
|
self.assertEqual(synopsis, 'line 1: h\xe9')
|
|
|
|
@unittest.skipIf(sys.flags.optimize >= 2,
|
|
'Docstrings are omitted with -OO and above')
|
|
def test_synopsis_sourceless(self):
|
|
expected = os.__doc__.splitlines()[0]
|
|
filename = os.__cached__
|
|
synopsis = pydoc.synopsis(filename)
|
|
|
|
self.assertEqual(synopsis, expected)
|
|
|
|
def test_synopsis_sourceless_empty_doc(self):
|
|
with test.support.temp_cwd() as test_dir:
|
|
init_path = os.path.join(test_dir, 'foomod42.py')
|
|
cached_path = importlib.util.cache_from_source(init_path)
|
|
with open(init_path, 'w') as fobj:
|
|
fobj.write("foo = 1")
|
|
py_compile.compile(init_path)
|
|
synopsis = pydoc.synopsis(init_path, {})
|
|
self.assertIsNone(synopsis)
|
|
synopsis_cached = pydoc.synopsis(cached_path, {})
|
|
self.assertIsNone(synopsis_cached)
|
|
|
|
def test_splitdoc_with_description(self):
|
|
example_string = "I Am A Doc\n\n\nHere is my description"
|
|
self.assertEqual(pydoc.splitdoc(example_string),
|
|
('I Am A Doc', '\nHere is my description'))
|
|
|
|
def test_is_package_when_not_package(self):
|
|
with test.support.temp_cwd() as test_dir:
|
|
self.assertFalse(pydoc.ispackage(test_dir))
|
|
|
|
def test_is_package_when_is_package(self):
|
|
with test.support.temp_cwd() as test_dir:
|
|
init_path = os.path.join(test_dir, '__init__.py')
|
|
open(init_path, 'w').close()
|
|
self.assertTrue(pydoc.ispackage(test_dir))
|
|
os.remove(init_path)
|
|
|
|
def test_allmethods(self):
|
|
# issue 17476: allmethods was no longer returning unbound methods.
|
|
# This test is a bit fragile in the face of changes to object and type,
|
|
# but I can't think of a better way to do it without duplicating the
|
|
# logic of the function under test.
|
|
|
|
class TestClass(object):
|
|
def method_returning_true(self):
|
|
return True
|
|
|
|
# What we expect to get back: everything on object...
|
|
expected = dict(vars(object))
|
|
# ...plus our unbound method...
|
|
expected['method_returning_true'] = TestClass.method_returning_true
|
|
# ...but not the non-methods on object.
|
|
del expected['__doc__']
|
|
del expected['__class__']
|
|
# inspect resolves descriptors on type into methods, but vars doesn't,
|
|
# so we need to update __subclasshook__ and __init_subclass__.
|
|
expected['__subclasshook__'] = TestClass.__subclasshook__
|
|
expected['__init_subclass__'] = TestClass.__init_subclass__
|
|
|
|
methods = pydoc.allmethods(TestClass)
|
|
self.assertDictEqual(methods, expected)
|
|
|
|
def test_method_aliases(self):
|
|
class A:
|
|
def tkraise(self, aboveThis=None):
|
|
"""Raise this widget in the stacking order."""
|
|
lift = tkraise
|
|
def a_size(self):
|
|
"""Return size"""
|
|
class B(A):
|
|
def itemconfigure(self, tagOrId, cnf=None, **kw):
|
|
"""Configure resources of an item TAGORID."""
|
|
itemconfig = itemconfigure
|
|
b_size = A.a_size
|
|
|
|
doc = pydoc.render_doc(B)
|
|
# clean up the extra text formatting that pydoc performs
|
|
doc = re.sub('\b.', '', doc)
|
|
self.assertEqual(doc, '''\
|
|
Python Library Documentation: class B in module %s
|
|
|
|
class B(A)
|
|
| Method resolution order:
|
|
| B
|
|
| A
|
|
| builtins.object
|
|
|\x20\x20
|
|
| Methods defined here:
|
|
|\x20\x20
|
|
| b_size = a_size(self)
|
|
|\x20\x20
|
|
| itemconfig = itemconfigure(self, tagOrId, cnf=None, **kw)
|
|
|\x20\x20
|
|
| itemconfigure(self, tagOrId, cnf=None, **kw)
|
|
| Configure resources of an item TAGORID.
|
|
|\x20\x20
|
|
| ----------------------------------------------------------------------
|
|
| Methods inherited from A:
|
|
|\x20\x20
|
|
| a_size(self)
|
|
| Return size
|
|
|\x20\x20
|
|
| lift = tkraise(self, aboveThis=None)
|
|
|\x20\x20
|
|
| tkraise(self, aboveThis=None)
|
|
| Raise this widget in the stacking order.
|
|
|\x20\x20
|
|
| ----------------------------------------------------------------------
|
|
| Data descriptors inherited from A:
|
|
|\x20\x20
|
|
| __dict__
|
|
| dictionary for instance variables (if defined)
|
|
|\x20\x20
|
|
| __weakref__
|
|
| list of weak references to the object (if defined)
|
|
''' % __name__)
|
|
|
|
doc = pydoc.render_doc(B, renderer=pydoc.HTMLDoc())
|
|
self.assertEqual(doc, '''\
|
|
Python Library Documentation: class B in module %s
|
|
|
|
<p>
|
|
<table width="100%%" cellspacing=0 cellpadding=2 border=0 summary="section">
|
|
<tr bgcolor="#ffc8d8">
|
|
<td colspan=3 valign=bottom> <br>
|
|
<font color="#000000" face="helvetica, arial"><a name="B">class <strong>B</strong></a>(A)</font></td></tr>
|
|
\x20\x20\x20\x20
|
|
<tr><td bgcolor="#ffc8d8"><tt> </tt></td><td> </td>
|
|
<td width="100%%"><dl><dt>Method resolution order:</dt>
|
|
<dd>B</dd>
|
|
<dd>A</dd>
|
|
<dd><a href="builtins.html#object">builtins.object</a></dd>
|
|
</dl>
|
|
<hr>
|
|
Methods defined here:<br>
|
|
<dl><dt><a name="B-b_size"><strong>b_size</strong></a> = <a href="#B-a_size">a_size</a>(self)</dt></dl>
|
|
|
|
<dl><dt><a name="B-itemconfig"><strong>itemconfig</strong></a> = <a href="#B-itemconfigure">itemconfigure</a>(self, tagOrId, cnf=None, **kw)</dt></dl>
|
|
|
|
<dl><dt><a name="B-itemconfigure"><strong>itemconfigure</strong></a>(self, tagOrId, cnf=None, **kw)</dt><dd><tt>Configure resources of an item TAGORID.</tt></dd></dl>
|
|
|
|
<hr>
|
|
Methods inherited from A:<br>
|
|
<dl><dt><a name="B-a_size"><strong>a_size</strong></a>(self)</dt><dd><tt>Return size</tt></dd></dl>
|
|
|
|
<dl><dt><a name="B-lift"><strong>lift</strong></a> = <a href="#B-tkraise">tkraise</a>(self, aboveThis=None)</dt></dl>
|
|
|
|
<dl><dt><a name="B-tkraise"><strong>tkraise</strong></a>(self, aboveThis=None)</dt><dd><tt>Raise this widget in the stacking order.</tt></dd></dl>
|
|
|
|
<hr>
|
|
Data descriptors inherited from A:<br>
|
|
<dl><dt><strong>__dict__</strong></dt>
|
|
<dd><tt>dictionary for instance variables (if defined)</tt></dd>
|
|
</dl>
|
|
<dl><dt><strong>__weakref__</strong></dt>
|
|
<dd><tt>list of weak references to the object (if defined)</tt></dd>
|
|
</dl>
|
|
</td></tr></table>\
|
|
''' % __name__)
|
|
|
|
|
|
class PydocImportTest(PydocBaseTest):
|
|
|
|
def setUp(self):
|
|
self.test_dir = os.mkdir(TESTFN)
|
|
self.addCleanup(rmtree, TESTFN)
|
|
importlib.invalidate_caches()
|
|
|
|
def test_badimport(self):
|
|
# This tests the fix for issue 5230, where if pydoc found the module
|
|
# but the module had an internal import error pydoc would report no doc
|
|
# found.
|
|
modname = 'testmod_xyzzy'
|
|
testpairs = (
|
|
('i_am_not_here', 'i_am_not_here'),
|
|
('test.i_am_not_here_either', 'test.i_am_not_here_either'),
|
|
('test.i_am_not_here.neither_am_i', 'test.i_am_not_here'),
|
|
('i_am_not_here.{}'.format(modname), 'i_am_not_here'),
|
|
('test.{}'.format(modname), 'test.{}'.format(modname)),
|
|
)
|
|
|
|
sourcefn = os.path.join(TESTFN, modname) + os.extsep + "py"
|
|
for importstring, expectedinmsg in testpairs:
|
|
with open(sourcefn, 'w') as f:
|
|
f.write("import {}\n".format(importstring))
|
|
result = run_pydoc(modname, PYTHONPATH=TESTFN).decode("ascii")
|
|
expected = badimport_pattern % (modname, expectedinmsg)
|
|
self.assertEqual(expected, result)
|
|
|
|
def test_apropos_with_bad_package(self):
|
|
# Issue 7425 - pydoc -k failed when bad package on path
|
|
pkgdir = os.path.join(TESTFN, "syntaxerr")
|
|
os.mkdir(pkgdir)
|
|
badsyntax = os.path.join(pkgdir, "__init__") + os.extsep + "py"
|
|
with open(badsyntax, 'w') as f:
|
|
f.write("invalid python syntax = $1\n")
|
|
with self.restrict_walk_packages(path=[TESTFN]):
|
|
with captured_stdout() as out:
|
|
with captured_stderr() as err:
|
|
pydoc.apropos('xyzzy')
|
|
# No result, no error
|
|
self.assertEqual(out.getvalue(), '')
|
|
self.assertEqual(err.getvalue(), '')
|
|
# The package name is still matched
|
|
with captured_stdout() as out:
|
|
with captured_stderr() as err:
|
|
pydoc.apropos('syntaxerr')
|
|
self.assertEqual(out.getvalue().strip(), 'syntaxerr')
|
|
self.assertEqual(err.getvalue(), '')
|
|
|
|
def test_apropos_with_unreadable_dir(self):
|
|
# Issue 7367 - pydoc -k failed when unreadable dir on path
|
|
self.unreadable_dir = os.path.join(TESTFN, "unreadable")
|
|
os.mkdir(self.unreadable_dir, 0)
|
|
self.addCleanup(os.rmdir, self.unreadable_dir)
|
|
# Note, on Windows the directory appears to be still
|
|
# readable so this is not really testing the issue there
|
|
with self.restrict_walk_packages(path=[TESTFN]):
|
|
with captured_stdout() as out:
|
|
with captured_stderr() as err:
|
|
pydoc.apropos('SOMEKEY')
|
|
# No result, no error
|
|
self.assertEqual(out.getvalue(), '')
|
|
self.assertEqual(err.getvalue(), '')
|
|
|
|
def test_apropos_empty_doc(self):
|
|
pkgdir = os.path.join(TESTFN, 'walkpkg')
|
|
os.mkdir(pkgdir)
|
|
self.addCleanup(rmtree, pkgdir)
|
|
init_path = os.path.join(pkgdir, '__init__.py')
|
|
with open(init_path, 'w') as fobj:
|
|
fobj.write("foo = 1")
|
|
current_mode = stat.S_IMODE(os.stat(pkgdir).st_mode)
|
|
try:
|
|
os.chmod(pkgdir, current_mode & ~stat.S_IEXEC)
|
|
with self.restrict_walk_packages(path=[TESTFN]), captured_stdout() as stdout:
|
|
pydoc.apropos('')
|
|
self.assertIn('walkpkg', stdout.getvalue())
|
|
finally:
|
|
os.chmod(pkgdir, current_mode)
|
|
|
|
def test_url_search_package_error(self):
|
|
# URL handler search should cope with packages that raise exceptions
|
|
pkgdir = os.path.join(TESTFN, "test_error_package")
|
|
os.mkdir(pkgdir)
|
|
init = os.path.join(pkgdir, "__init__.py")
|
|
with open(init, "wt", encoding="ascii") as f:
|
|
f.write("""raise ValueError("ouch")\n""")
|
|
with self.restrict_walk_packages(path=[TESTFN]):
|
|
# Package has to be importable for the error to have any effect
|
|
saved_paths = tuple(sys.path)
|
|
sys.path.insert(0, TESTFN)
|
|
try:
|
|
with self.assertRaisesRegex(ValueError, "ouch"):
|
|
import test_error_package # Sanity check
|
|
|
|
text = self.call_url_handler("search?key=test_error_package",
|
|
"Pydoc: Search Results")
|
|
found = ('<a href="test_error_package.html">'
|
|
'test_error_package</a>')
|
|
self.assertIn(found, text)
|
|
finally:
|
|
sys.path[:] = saved_paths
|
|
|
|
@unittest.skip('causes undesirable side-effects (#20128)')
|
|
def test_modules(self):
|
|
# See Helper.listmodules().
|
|
num_header_lines = 2
|
|
num_module_lines_min = 5 # Playing it safe.
|
|
num_footer_lines = 3
|
|
expected = num_header_lines + num_module_lines_min + num_footer_lines
|
|
|
|
output = StringIO()
|
|
helper = pydoc.Helper(output=output)
|
|
helper('modules')
|
|
result = output.getvalue().strip()
|
|
num_lines = len(result.splitlines())
|
|
|
|
self.assertGreaterEqual(num_lines, expected)
|
|
|
|
@unittest.skip('causes undesirable side-effects (#20128)')
|
|
def test_modules_search(self):
|
|
# See Helper.listmodules().
|
|
expected = 'pydoc - '
|
|
|
|
output = StringIO()
|
|
helper = pydoc.Helper(output=output)
|
|
with captured_stdout() as help_io:
|
|
helper('modules pydoc')
|
|
result = help_io.getvalue()
|
|
|
|
self.assertIn(expected, result)
|
|
|
|
@unittest.skip('some buildbots are not cooperating (#20128)')
|
|
def test_modules_search_builtin(self):
|
|
expected = 'gc - '
|
|
|
|
output = StringIO()
|
|
helper = pydoc.Helper(output=output)
|
|
with captured_stdout() as help_io:
|
|
helper('modules garbage')
|
|
result = help_io.getvalue()
|
|
|
|
self.assertTrue(result.startswith(expected))
|
|
|
|
def test_importfile(self):
|
|
loaded_pydoc = pydoc.importfile(pydoc.__file__)
|
|
|
|
self.assertIsNot(loaded_pydoc, pydoc)
|
|
self.assertEqual(loaded_pydoc.__name__, 'pydoc')
|
|
self.assertEqual(loaded_pydoc.__file__, pydoc.__file__)
|
|
self.assertEqual(loaded_pydoc.__spec__, pydoc.__spec__)
|
|
|
|
|
|
class TestDescriptions(unittest.TestCase):
|
|
|
|
def test_module(self):
|
|
# Check that pydocfodder module can be described
|
|
from test import pydocfodder
|
|
doc = pydoc.render_doc(pydocfodder)
|
|
self.assertIn("pydocfodder", doc)
|
|
|
|
def test_class(self):
|
|
class C: "New-style class"
|
|
c = C()
|
|
|
|
self.assertEqual(pydoc.describe(C), 'class C')
|
|
self.assertEqual(pydoc.describe(c), 'C')
|
|
expected = 'C in module %s object' % __name__
|
|
self.assertIn(expected, pydoc.render_doc(c))
|
|
|
|
def test_typing_pydoc(self):
|
|
def foo(data: typing.List[typing.Any],
|
|
x: int) -> typing.Iterator[typing.Tuple[int, typing.Any]]:
|
|
...
|
|
T = typing.TypeVar('T')
|
|
class C(typing.Generic[T], typing.Mapping[int, str]): ...
|
|
self.assertEqual(pydoc.render_doc(foo).splitlines()[-1],
|
|
'f\x08fo\x08oo\x08o(data: List[Any], x: int)'
|
|
' -> Iterator[Tuple[int, Any]]')
|
|
self.assertEqual(pydoc.render_doc(C).splitlines()[2],
|
|
'class C\x08C(collections.abc.Mapping, typing.Generic)')
|
|
|
|
def test_builtin(self):
|
|
for name in ('str', 'str.translate', 'builtins.str',
|
|
'builtins.str.translate'):
|
|
# test low-level function
|
|
self.assertIsNotNone(pydoc.locate(name))
|
|
# test high-level function
|
|
try:
|
|
pydoc.render_doc(name)
|
|
except ImportError:
|
|
self.fail('finding the doc of {!r} failed'.format(name))
|
|
|
|
for name in ('notbuiltins', 'strrr', 'strr.translate',
|
|
'str.trrrranslate', 'builtins.strrr',
|
|
'builtins.str.trrranslate'):
|
|
self.assertIsNone(pydoc.locate(name))
|
|
self.assertRaises(ImportError, pydoc.render_doc, name)
|
|
|
|
@staticmethod
|
|
def _get_summary_line(o):
|
|
text = pydoc.plain(pydoc.render_doc(o))
|
|
lines = text.split('\n')
|
|
assert len(lines) >= 2
|
|
return lines[2]
|
|
|
|
@staticmethod
|
|
def _get_summary_lines(o):
|
|
text = pydoc.plain(pydoc.render_doc(o))
|
|
lines = text.split('\n')
|
|
return '\n'.join(lines[2:])
|
|
|
|
# these should include "self"
|
|
def test_unbound_python_method(self):
|
|
self.assertEqual(self._get_summary_line(textwrap.TextWrapper.wrap),
|
|
"wrap(self, text)")
|
|
|
|
@requires_docstrings
|
|
def test_unbound_builtin_method(self):
|
|
self.assertEqual(self._get_summary_line(_pickle.Pickler.dump),
|
|
"dump(self, obj, /)")
|
|
|
|
# these no longer include "self"
|
|
def test_bound_python_method(self):
|
|
t = textwrap.TextWrapper()
|
|
self.assertEqual(self._get_summary_line(t.wrap),
|
|
"wrap(text) method of textwrap.TextWrapper instance")
|
|
def test_field_order_for_named_tuples(self):
|
|
Person = namedtuple('Person', ['nickname', 'firstname', 'agegroup'])
|
|
s = pydoc.render_doc(Person)
|
|
self.assertLess(s.index('nickname'), s.index('firstname'))
|
|
self.assertLess(s.index('firstname'), s.index('agegroup'))
|
|
|
|
class NonIterableFields:
|
|
_fields = None
|
|
|
|
class NonHashableFields:
|
|
_fields = [[]]
|
|
|
|
# Make sure these doesn't fail
|
|
pydoc.render_doc(NonIterableFields)
|
|
pydoc.render_doc(NonHashableFields)
|
|
|
|
@requires_docstrings
|
|
def test_bound_builtin_method(self):
|
|
s = StringIO()
|
|
p = _pickle.Pickler(s)
|
|
self.assertEqual(self._get_summary_line(p.dump),
|
|
"dump(obj, /) method of _pickle.Pickler instance")
|
|
|
|
# this should *never* include self!
|
|
@requires_docstrings
|
|
def test_module_level_callable(self):
|
|
self.assertEqual(self._get_summary_line(os.stat),
|
|
"stat(path, *, dir_fd=None, follow_symlinks=True)")
|
|
|
|
@requires_docstrings
|
|
def test_staticmethod(self):
|
|
class X:
|
|
@staticmethod
|
|
def sm(x, y):
|
|
'''A static method'''
|
|
...
|
|
self.assertEqual(self._get_summary_lines(X.__dict__['sm']),
|
|
"<staticmethod object>")
|
|
self.assertEqual(self._get_summary_lines(X.sm), """\
|
|
sm(x, y)
|
|
A static method
|
|
""")
|
|
self.assertIn("""
|
|
| Static methods defined here:
|
|
|\x20\x20
|
|
| sm(x, y)
|
|
| A static method
|
|
""", pydoc.plain(pydoc.render_doc(X)))
|
|
|
|
@requires_docstrings
|
|
def test_classmethod(self):
|
|
class X:
|
|
@classmethod
|
|
def cm(cls, x):
|
|
'''A class method'''
|
|
...
|
|
self.assertEqual(self._get_summary_lines(X.__dict__['cm']),
|
|
"<classmethod object>")
|
|
self.assertEqual(self._get_summary_lines(X.cm), """\
|
|
cm(x) method of builtins.type instance
|
|
A class method
|
|
""")
|
|
self.assertIn("""
|
|
| Class methods defined here:
|
|
|\x20\x20
|
|
| cm(x) from builtins.type
|
|
| A class method
|
|
""", pydoc.plain(pydoc.render_doc(X)))
|
|
|
|
@requires_docstrings
|
|
def test_getset_descriptor(self):
|
|
# Currently these attributes are implemented as getset descriptors
|
|
# in CPython.
|
|
self.assertEqual(self._get_summary_line(int.numerator), "numerator")
|
|
self.assertEqual(self._get_summary_line(float.real), "real")
|
|
self.assertEqual(self._get_summary_line(Exception.args), "args")
|
|
self.assertEqual(self._get_summary_line(memoryview.obj), "obj")
|
|
|
|
@requires_docstrings
|
|
def test_member_descriptor(self):
|
|
# Currently these attributes are implemented as member descriptors
|
|
# in CPython.
|
|
self.assertEqual(self._get_summary_line(complex.real), "real")
|
|
self.assertEqual(self._get_summary_line(range.start), "start")
|
|
self.assertEqual(self._get_summary_line(slice.start), "start")
|
|
self.assertEqual(self._get_summary_line(property.fget), "fget")
|
|
self.assertEqual(self._get_summary_line(StopIteration.value), "value")
|
|
|
|
@requires_docstrings
|
|
def test_slot_descriptor(self):
|
|
class Point:
|
|
__slots__ = 'x', 'y'
|
|
self.assertEqual(self._get_summary_line(Point.x), "x")
|
|
|
|
@requires_docstrings
|
|
def test_dict_attr_descriptor(self):
|
|
class NS:
|
|
pass
|
|
self.assertEqual(self._get_summary_line(NS.__dict__['__dict__']),
|
|
"__dict__")
|
|
|
|
@requires_docstrings
|
|
def test_structseq_member_descriptor(self):
|
|
self.assertEqual(self._get_summary_line(type(sys.hash_info).width),
|
|
"width")
|
|
self.assertEqual(self._get_summary_line(type(sys.flags).debug),
|
|
"debug")
|
|
self.assertEqual(self._get_summary_line(type(sys.version_info).major),
|
|
"major")
|
|
self.assertEqual(self._get_summary_line(type(sys.float_info).max),
|
|
"max")
|
|
|
|
@requires_docstrings
|
|
def test_namedtuple_field_descriptor(self):
|
|
Box = namedtuple('Box', ('width', 'height'))
|
|
self.assertEqual(self._get_summary_lines(Box.width), """\
|
|
Alias for field number 0
|
|
""")
|
|
|
|
@requires_docstrings
|
|
def test_property(self):
|
|
class Rect:
|
|
@property
|
|
def area(self):
|
|
'''Area of the rect'''
|
|
return self.w * self.h
|
|
|
|
self.assertEqual(self._get_summary_lines(Rect.area), """\
|
|
Area of the rect
|
|
""")
|
|
self.assertIn("""
|
|
| area
|
|
| Area of the rect
|
|
""", pydoc.plain(pydoc.render_doc(Rect)))
|
|
|
|
@requires_docstrings
|
|
def test_custom_non_data_descriptor(self):
|
|
class Descr:
|
|
def __get__(self, obj, cls):
|
|
if obj is None:
|
|
return self
|
|
return 42
|
|
class X:
|
|
attr = Descr()
|
|
|
|
self.assertEqual(self._get_summary_lines(X.attr), """\
|
|
<test.test_pydoc.TestDescriptions.test_custom_non_data_descriptor.<locals>.Descr object>""")
|
|
|
|
X.attr.__doc__ = 'Custom descriptor'
|
|
self.assertEqual(self._get_summary_lines(X.attr), """\
|
|
<test.test_pydoc.TestDescriptions.test_custom_non_data_descriptor.<locals>.Descr object>""")
|
|
|
|
X.attr.__name__ = 'foo'
|
|
self.assertEqual(self._get_summary_lines(X.attr), """\
|
|
foo(...)
|
|
Custom descriptor
|
|
""")
|
|
|
|
@requires_docstrings
|
|
def test_custom_data_descriptor(self):
|
|
class Descr:
|
|
def __get__(self, obj, cls):
|
|
if obj is None:
|
|
return self
|
|
return 42
|
|
def __set__(self, obj, cls):
|
|
1/0
|
|
class X:
|
|
attr = Descr()
|
|
|
|
self.assertEqual(self._get_summary_lines(X.attr), "")
|
|
|
|
X.attr.__doc__ = 'Custom descriptor'
|
|
self.assertEqual(self._get_summary_lines(X.attr), """\
|
|
Custom descriptor
|
|
""")
|
|
|
|
X.attr.__name__ = 'foo'
|
|
self.assertEqual(self._get_summary_lines(X.attr), """\
|
|
foo
|
|
Custom descriptor
|
|
""")
|
|
|
|
def test_async_annotation(self):
|
|
async def coro_function(ign) -> int:
|
|
return 1
|
|
|
|
text = pydoc.plain(pydoc.plaintext.document(coro_function))
|
|
self.assertIn('async coro_function', text)
|
|
|
|
html = pydoc.HTMLDoc().document(coro_function)
|
|
self.assertIn(
|
|
'async <a name="-coro_function"><strong>coro_function',
|
|
html)
|
|
|
|
def test_async_generator_annotation(self):
|
|
async def an_async_generator():
|
|
yield 1
|
|
|
|
text = pydoc.plain(pydoc.plaintext.document(an_async_generator))
|
|
self.assertIn('async an_async_generator', text)
|
|
|
|
html = pydoc.HTMLDoc().document(an_async_generator)
|
|
self.assertIn(
|
|
'async <a name="-an_async_generator"><strong>an_async_generator',
|
|
html)
|
|
|
|
class PydocServerTest(unittest.TestCase):
|
|
"""Tests for pydoc._start_server"""
|
|
|
|
def test_server(self):
|
|
|
|
# Minimal test that starts the server, then stops it.
|
|
def my_url_handler(url, content_type):
|
|
text = 'the URL sent was: (%s, %s)' % (url, content_type)
|
|
return text
|
|
|
|
serverthread = pydoc._start_server(my_url_handler, hostname='0.0.0.0', port=0)
|
|
self.assertIn('0.0.0.0', serverthread.docserver.address)
|
|
|
|
starttime = time.monotonic()
|
|
timeout = 1 #seconds
|
|
|
|
while serverthread.serving:
|
|
time.sleep(.01)
|
|
if serverthread.serving and time.monotonic() - starttime > timeout:
|
|
serverthread.stop()
|
|
break
|
|
|
|
self.assertEqual(serverthread.error, None)
|
|
|
|
|
|
class PydocUrlHandlerTest(PydocBaseTest):
|
|
"""Tests for pydoc._url_handler"""
|
|
|
|
def test_content_type_err(self):
|
|
f = pydoc._url_handler
|
|
self.assertRaises(TypeError, f, 'A', '')
|
|
self.assertRaises(TypeError, f, 'B', 'foobar')
|
|
|
|
def test_url_requests(self):
|
|
# Test for the correct title in the html pages returned.
|
|
# This tests the different parts of the URL handler without
|
|
# getting too picky about the exact html.
|
|
requests = [
|
|
("", "Pydoc: Index of Modules"),
|
|
("get?key=", "Pydoc: Index of Modules"),
|
|
("index", "Pydoc: Index of Modules"),
|
|
("topics", "Pydoc: Topics"),
|
|
("keywords", "Pydoc: Keywords"),
|
|
("pydoc", "Pydoc: module pydoc"),
|
|
("get?key=pydoc", "Pydoc: module pydoc"),
|
|
("search?key=pydoc", "Pydoc: Search Results"),
|
|
("topic?key=def", "Pydoc: KEYWORD def"),
|
|
("topic?key=STRINGS", "Pydoc: TOPIC STRINGS"),
|
|
("foobar", "Pydoc: Error - foobar"),
|
|
("getfile?key=foobar", "Pydoc: Error - getfile?key=foobar"),
|
|
]
|
|
|
|
with self.restrict_walk_packages():
|
|
for url, title in requests:
|
|
self.call_url_handler(url, title)
|
|
|
|
path = string.__file__
|
|
title = "Pydoc: getfile " + path
|
|
url = "getfile?key=" + path
|
|
self.call_url_handler(url, title)
|
|
|
|
|
|
class TestHelper(unittest.TestCase):
|
|
def test_keywords(self):
|
|
self.assertEqual(sorted(pydoc.Helper.keywords),
|
|
sorted(keyword.kwlist))
|
|
|
|
class PydocWithMetaClasses(unittest.TestCase):
|
|
@unittest.skipIf(sys.flags.optimize >= 2,
|
|
"Docstrings are omitted with -O2 and above")
|
|
@unittest.skipIf(hasattr(sys, 'gettrace') and sys.gettrace(),
|
|
'trace function introduces __locals__ unexpectedly')
|
|
def test_DynamicClassAttribute(self):
|
|
class Meta(type):
|
|
def __getattr__(self, name):
|
|
if name == 'ham':
|
|
return 'spam'
|
|
return super().__getattr__(name)
|
|
class DA(metaclass=Meta):
|
|
@types.DynamicClassAttribute
|
|
def ham(self):
|
|
return 'eggs'
|
|
expected_text_data_docstrings = tuple('\n | ' + s if s else ''
|
|
for s in expected_data_docstrings)
|
|
output = StringIO()
|
|
helper = pydoc.Helper(output=output)
|
|
helper(DA)
|
|
expected_text = expected_dynamicattribute_pattern % (
|
|
(__name__,) + expected_text_data_docstrings[:2])
|
|
result = output.getvalue().strip()
|
|
self.assertEqual(expected_text, result)
|
|
|
|
@unittest.skipIf(sys.flags.optimize >= 2,
|
|
"Docstrings are omitted with -O2 and above")
|
|
@unittest.skipIf(hasattr(sys, 'gettrace') and sys.gettrace(),
|
|
'trace function introduces __locals__ unexpectedly')
|
|
def test_virtualClassAttributeWithOneMeta(self):
|
|
class Meta(type):
|
|
def __dir__(cls):
|
|
return ['__class__', '__module__', '__name__', 'LIFE']
|
|
def __getattr__(self, name):
|
|
if name =='LIFE':
|
|
return 42
|
|
return super().__getattr(name)
|
|
class Class(metaclass=Meta):
|
|
pass
|
|
output = StringIO()
|
|
helper = pydoc.Helper(output=output)
|
|
helper(Class)
|
|
expected_text = expected_virtualattribute_pattern1 % __name__
|
|
result = output.getvalue().strip()
|
|
self.assertEqual(expected_text, result)
|
|
|
|
@unittest.skipIf(sys.flags.optimize >= 2,
|
|
"Docstrings are omitted with -O2 and above")
|
|
@unittest.skipIf(hasattr(sys, 'gettrace') and sys.gettrace(),
|
|
'trace function introduces __locals__ unexpectedly')
|
|
def test_virtualClassAttributeWithTwoMeta(self):
|
|
class Meta1(type):
|
|
def __dir__(cls):
|
|
return ['__class__', '__module__', '__name__', 'one']
|
|
def __getattr__(self, name):
|
|
if name =='one':
|
|
return 1
|
|
return super().__getattr__(name)
|
|
class Meta2(type):
|
|
def __dir__(cls):
|
|
return ['__class__', '__module__', '__name__', 'two']
|
|
def __getattr__(self, name):
|
|
if name =='two':
|
|
return 2
|
|
return super().__getattr__(name)
|
|
class Meta3(Meta1, Meta2):
|
|
def __dir__(cls):
|
|
return list(sorted(set(
|
|
['__class__', '__module__', '__name__', 'three'] +
|
|
Meta1.__dir__(cls) + Meta2.__dir__(cls))))
|
|
def __getattr__(self, name):
|
|
if name =='three':
|
|
return 3
|
|
return super().__getattr__(name)
|
|
class Class1(metaclass=Meta1):
|
|
pass
|
|
class Class2(Class1, metaclass=Meta3):
|
|
pass
|
|
fail1 = fail2 = False
|
|
output = StringIO()
|
|
helper = pydoc.Helper(output=output)
|
|
helper(Class1)
|
|
expected_text1 = expected_virtualattribute_pattern2 % __name__
|
|
result1 = output.getvalue().strip()
|
|
self.assertEqual(expected_text1, result1)
|
|
output = StringIO()
|
|
helper = pydoc.Helper(output=output)
|
|
helper(Class2)
|
|
expected_text2 = expected_virtualattribute_pattern3 % __name__
|
|
result2 = output.getvalue().strip()
|
|
self.assertEqual(expected_text2, result2)
|
|
|
|
@unittest.skipIf(sys.flags.optimize >= 2,
|
|
"Docstrings are omitted with -O2 and above")
|
|
@unittest.skipIf(hasattr(sys, 'gettrace') and sys.gettrace(),
|
|
'trace function introduces __locals__ unexpectedly')
|
|
def test_buggy_dir(self):
|
|
class M(type):
|
|
def __dir__(cls):
|
|
return ['__class__', '__name__', 'missing', 'here']
|
|
class C(metaclass=M):
|
|
here = 'present!'
|
|
output = StringIO()
|
|
helper = pydoc.Helper(output=output)
|
|
helper(C)
|
|
expected_text = expected_missingattribute_pattern % __name__
|
|
result = output.getvalue().strip()
|
|
self.assertEqual(expected_text, result)
|
|
|
|
def test_resolve_false(self):
|
|
# Issue #23008: pydoc enum.{,Int}Enum failed
|
|
# because bool(enum.Enum) is False.
|
|
with captured_stdout() as help_io:
|
|
pydoc.help('enum.Enum')
|
|
helptext = help_io.getvalue()
|
|
self.assertIn('class Enum', helptext)
|
|
|
|
|
|
class TestInternalUtilities(unittest.TestCase):
|
|
|
|
def setUp(self):
|
|
tmpdir = tempfile.TemporaryDirectory()
|
|
self.argv0dir = tmpdir.name
|
|
self.argv0 = os.path.join(tmpdir.name, "nonexistent")
|
|
self.addCleanup(tmpdir.cleanup)
|
|
self.abs_curdir = abs_curdir = os.getcwd()
|
|
self.curdir_spellings = ["", os.curdir, abs_curdir]
|
|
|
|
def _get_revised_path(self, given_path, argv0=None):
|
|
# Checking that pydoc.cli() actually calls pydoc._get_revised_path()
|
|
# is handled via code review (at least for now).
|
|
if argv0 is None:
|
|
argv0 = self.argv0
|
|
return pydoc._get_revised_path(given_path, argv0)
|
|
|
|
def _get_starting_path(self):
|
|
# Get a copy of sys.path without the current directory.
|
|
clean_path = sys.path.copy()
|
|
for spelling in self.curdir_spellings:
|
|
for __ in range(clean_path.count(spelling)):
|
|
clean_path.remove(spelling)
|
|
return clean_path
|
|
|
|
def test_sys_path_adjustment_adds_missing_curdir(self):
|
|
clean_path = self._get_starting_path()
|
|
expected_path = [self.abs_curdir] + clean_path
|
|
self.assertEqual(self._get_revised_path(clean_path), expected_path)
|
|
|
|
def test_sys_path_adjustment_removes_argv0_dir(self):
|
|
clean_path = self._get_starting_path()
|
|
expected_path = [self.abs_curdir] + clean_path
|
|
leading_argv0dir = [self.argv0dir] + clean_path
|
|
self.assertEqual(self._get_revised_path(leading_argv0dir), expected_path)
|
|
trailing_argv0dir = clean_path + [self.argv0dir]
|
|
self.assertEqual(self._get_revised_path(trailing_argv0dir), expected_path)
|
|
|
|
|
|
def test_sys_path_adjustment_protects_pydoc_dir(self):
|
|
def _get_revised_path(given_path):
|
|
return self._get_revised_path(given_path, argv0=pydoc.__file__)
|
|
clean_path = self._get_starting_path()
|
|
leading_argv0dir = [self.argv0dir] + clean_path
|
|
expected_path = [self.abs_curdir] + leading_argv0dir
|
|
self.assertEqual(_get_revised_path(leading_argv0dir), expected_path)
|
|
trailing_argv0dir = clean_path + [self.argv0dir]
|
|
expected_path = [self.abs_curdir] + trailing_argv0dir
|
|
self.assertEqual(_get_revised_path(trailing_argv0dir), expected_path)
|
|
|
|
def test_sys_path_adjustment_when_curdir_already_included(self):
|
|
clean_path = self._get_starting_path()
|
|
for spelling in self.curdir_spellings:
|
|
with self.subTest(curdir_spelling=spelling):
|
|
# If curdir is already present, no alterations are made at all
|
|
leading_curdir = [spelling] + clean_path
|
|
self.assertIsNone(self._get_revised_path(leading_curdir))
|
|
trailing_curdir = clean_path + [spelling]
|
|
self.assertIsNone(self._get_revised_path(trailing_curdir))
|
|
leading_argv0dir = [self.argv0dir] + leading_curdir
|
|
self.assertIsNone(self._get_revised_path(leading_argv0dir))
|
|
trailing_argv0dir = trailing_curdir + [self.argv0dir]
|
|
self.assertIsNone(self._get_revised_path(trailing_argv0dir))
|
|
|
|
|
|
@reap_threads
|
|
def test_main():
|
|
try:
|
|
test.support.run_unittest(PydocDocTest,
|
|
PydocImportTest,
|
|
TestDescriptions,
|
|
PydocServerTest,
|
|
PydocUrlHandlerTest,
|
|
TestHelper,
|
|
PydocWithMetaClasses,
|
|
TestInternalUtilities,
|
|
)
|
|
finally:
|
|
reap_children()
|
|
|
|
if __name__ == "__main__":
|
|
test_main()
|