From: Serhiy Storchaka <storchaka@gmail.com>
Date: Sat, 18 Apr 2020 14:13:21 +0000 (+0300)
Subject: bpo-40257: Improve help for the typing module (GH-19546)
X-Git-Tag: v3.9.0a6~76
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=7e64414f57b70dc5bc0ab19a3162a0735f9bfabf;p=thirdparty%2FPython%2Fcpython.git

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.
---

diff --git a/Doc/whatsnew/3.9.rst b/Doc/whatsnew/3.9.rst
index 2b36b0f154b3..8147d8f185c7 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 a89b8045709c..898cc44b295e 100755
--- a/Lib/pydoc.py
+++ b/Lib/pydoc.py
@@ -1445,7 +1445,7 @@ location listed above.
         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 800913b425a2..6d358f4fe2fc 100644
--- a/Lib/test/test_pydoc.py
+++ b/Lib/test/test_pydoc.py
@@ -1255,7 +1255,8 @@ cm(x) method of builtins.type instance
         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 9cacaa840ca3..df3650001e78 100644
--- a/Lib/typing.py
+++ b/Lib/typing.py
@@ -323,6 +323,10 @@ class _SpecialForm(_Final, _Immutable, _root=True):
         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 @@ class _GenericAlias(_Final, _root=True):
         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 000000000000..6ed094add1f6
--- /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).