[Python-checkins] bpo-40257: Improve help for the typing module (GH-19546)
Serhiy Storchaka
webhook-mailer at python.org
Sat Apr 18 10:13:26 EDT 2020
https://github.com/python/cpython/commit/7e64414f57b70dc5bc0ab19a3162a0735f9bfabf
commit: 7e64414f57b70dc5bc0ab19a3162a0735f9bfabf
branch: master
author: Serhiy Storchaka <storchaka at gmail.com>
committer: GitHub <noreply at github.com>
date: 2020-04-18T17:13:21+03:00
summary:
bpo-40257: Improve help for the typing module (GH-19546)
* Show docstring for special forms.
* Show docstring for special generic aliases.
* Show documentation for __origin__ for generic aliases.
files:
A Misc/NEWS.d/next/Library/2020-04-18-10-52-15.bpo-40257.lv4WTq.rst
M Doc/whatsnew/3.9.rst
M Lib/pydoc.py
M Lib/test/test_pydoc.py
M Lib/typing.py
diff --git a/Doc/whatsnew/3.9.rst b/Doc/whatsnew/3.9.rst
index 2b36b0f154b31..8147d8f185c7c 100644
--- a/Doc/whatsnew/3.9.rst
+++ b/Doc/whatsnew/3.9.rst
@@ -142,6 +142,12 @@ Other Language Changes
grammar was much more restrictive. See :pep:`614` for details.
(Contributed by Brandt Bucher in :issue:`39702`.)
+* Improved help for the :mod:`typing` module. Docstrings are now shown for
+ all special forms and special generic aliases (like ``Union`` and ``List``).
+ Using :func:`help` with generic alias like ``List[int]`` will show the help
+ for the correspondent concrete type (``list`` in this case).
+ (Contributed by Serhiy Storchaka in :issue:`40257`.)
+
New Modules
===========
diff --git a/Lib/pydoc.py b/Lib/pydoc.py
index a89b8045709c2..898cc44b295ee 100755
--- a/Lib/pydoc.py
+++ b/Lib/pydoc.py
@@ -1445,7 +1445,7 @@ def docother(self, object, name=None, mod=None, parent=None, maxlen=None, doc=No
if not doc:
doc = getdoc(object)
if doc:
- line += '\n' + self.indent(str(doc))
+ line += '\n' + self.indent(str(doc)) + '\n'
return line
class _PlainTextDoc(TextDoc):
@@ -1672,8 +1672,11 @@ def render_doc(thing, title='Python Library Documentation: %s', forceload=0,
inspect.getdoc(object)):
# If the passed object is a piece of data or an instance,
# document its available methods instead of its value.
- object = type(object)
- desc += ' object'
+ if hasattr(object, '__origin__'):
+ object = object.__origin__
+ else:
+ object = type(object)
+ desc += ' object'
return title % desc + '\n\n' + renderer.document(object, name)
def doc(thing, title='Python Library Documentation: %s', forceload=0,
diff --git a/Lib/test/test_pydoc.py b/Lib/test/test_pydoc.py
index 800913b425a25..6d358f4fe2fc3 100644
--- a/Lib/test/test_pydoc.py
+++ b/Lib/test/test_pydoc.py
@@ -1255,7 +1255,8 @@ class X:
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>
- Custom descriptor""")
+ Custom descriptor
+""")
X.attr.__name__ = 'foo'
self.assertEqual(self._get_summary_lines(X.attr), """\
diff --git a/Lib/typing.py b/Lib/typing.py
index 9cacaa840ca35..df3650001e78e 100644
--- a/Lib/typing.py
+++ b/Lib/typing.py
@@ -323,6 +323,10 @@ def __init__(self, name, doc):
self._name = name
self._doc = doc
+ @property
+ def __doc__(self):
+ return self._doc
+
def __eq__(self, other):
if not isinstance(other, _SpecialForm):
return NotImplemented
@@ -672,6 +676,8 @@ def __init__(self, origin, params, *, inst=True, special=False, name=None):
self.__slots__ = None # This is not documented.
if not name:
self.__module__ = origin.__module__
+ if special:
+ self.__doc__ = f'A generic version of {origin.__module__}.{origin.__qualname__}'
@_tp_cache
def __getitem__(self, params):
diff --git a/Misc/NEWS.d/next/Library/2020-04-18-10-52-15.bpo-40257.lv4WTq.rst b/Misc/NEWS.d/next/Library/2020-04-18-10-52-15.bpo-40257.lv4WTq.rst
new file mode 100644
index 0000000000000..6ed094add1f62
--- /dev/null
+++ b/Misc/NEWS.d/next/Library/2020-04-18-10-52-15.bpo-40257.lv4WTq.rst
@@ -0,0 +1,4 @@
+Improved help for the :mod:`typing` module. Docstrings are now shown for all
+special forms and special generic aliases (like ``Union`` and ``List``).
+Using ``help()`` with generic alias like ``List[int]`` will show the help
+for the correspondent concrete type (``list`` in this case).
More information about the Python-checkins
mailing list