From 24a882bb7bc638644b9e66a082439416bfbcf66c Mon Sep 17 00:00:00 2001
From: Larry Hastings <larry@hastings.org>
Date: Thu, 20 Feb 2014 23:34:46 -0800
Subject: [PATCH] Issue #20710: The pydoc summary line no longer displays the
 "self" parameter for bound methods.  Previous to this change, it displayed
 "self" for methods implemented in Python but not methods implemented in C; it
 is now both internally consistent and consistent with inspect.Signature.

---
 Lib/pydoc.py           | 21 ++++++++++++++++-----
 Lib/test/test_pydoc.py | 40 +++++++++++++++++++++++++++++++++++-----
 Misc/NEWS              |  3 +++
 3 files changed, 54 insertions(+), 10 deletions(-)

diff --git a/Lib/pydoc.py b/Lib/pydoc.py
index 3873d5554a..505b7cbd58 100755
--- a/Lib/pydoc.py
+++ b/Lib/pydoc.py
@@ -137,6 +137,19 @@ def _is_some_method(obj):
             inspect.isbuiltin(obj) or
             inspect.ismethoddescriptor(obj))
 
+def _is_bound_method(fn):
+    """
+    Returns True if fn is a bound method, regardless of whether
+    fn was implemented in Python or in C.
+    """
+    if inspect.ismethod(fn):
+        return True
+    if inspect.isbuiltin(fn):
+        self = getattr(fn, '__self__', None)
+        return not (inspect.ismodule(self) or (self is None))
+    return False
+
+
 def allmethods(cl):
     methods = {}
     for key, value in inspect.getmembers(cl, _is_some_method):
@@ -898,7 +911,7 @@ class HTMLDoc(Doc):
         anchor = (cl and cl.__name__ or '') + '-' + name
         note = ''
         skipdocs = 0
-        if inspect.ismethod(object):
+        if _is_bound_method(object):
             imclass = object.__self__.__class__
             if cl:
                 if imclass is not cl:
@@ -909,7 +922,6 @@ class HTMLDoc(Doc):
                         object.__self__.__class__, mod)
                 else:
                     note = ' unbound %s method' % self.classlink(imclass,mod)
-            object = object.__func__
 
         if name == realname:
             title = '<a name="%s"><strong>%s</strong></a>' % (anchor, realname)
@@ -924,7 +936,7 @@ class HTMLDoc(Doc):
             title = '<a name="%s"><strong>%s</strong></a> = %s' % (
                 anchor, name, reallink)
         argspec = None
-        if inspect.isfunction(object) or inspect.isbuiltin(object):
+        if inspect.isroutine(object):
             try:
                 signature = inspect.signature(object)
             except (ValueError, TypeError):
@@ -1304,7 +1316,7 @@ location listed above.
         name = name or realname
         note = ''
         skipdocs = 0
-        if inspect.ismethod(object):
+        if _is_bound_method(object):
             imclass = object.__self__.__class__
             if cl:
                 if imclass is not cl:
@@ -1315,7 +1327,6 @@ location listed above.
                         object.__self__.__class__, mod)
                 else:
                     note = ' unbound %s method' % classname(imclass,mod)
-            object = object.__func__
 
         if name == realname:
             title = self.bold(realname)
diff --git a/Lib/test/test_pydoc.py b/Lib/test/test_pydoc.py
index 9909b9ae53..96b923077f 100644
--- a/Lib/test/test_pydoc.py
+++ b/Lib/test/test_pydoc.py
@@ -6,6 +6,7 @@ import difflib
 import inspect
 import pydoc
 import keyword
+import _pickle
 import pkgutil
 import re
 import string
@@ -699,12 +700,41 @@ class TestDescriptions(unittest.TestCase):
             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]
+
+    # 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")
+
+    @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_builtin_signatures(self):
-        # test producing signatures from builtins
-        stat_sig = pydoc.render_doc(os.stat)
-        self.assertEqual(pydoc.plain(stat_sig).splitlines()[2],
-            'stat(path, *, dir_fd=None, follow_symlinks=True)')
+    def test_module_level_callable(self):
+        self.assertEqual(self._get_summary_line(os.stat),
+            "stat(path, *, dir_fd=None, follow_symlinks=True)")
 
 
 @unittest.skipUnless(threading, 'Threading required for this test.')
diff --git a/Misc/NEWS b/Misc/NEWS
index edb5f71751..b4374cc487 100644
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -28,6 +28,9 @@ Core and Builtins
 Library
 -------
 
+- Issue #20710: The pydoc summary line no longer displays the "self" parameter
+  for bound methods.
+
 - Issue #20654: Fixed pydoc for enums with zero value.  Patch by Vajrasky Kok.
 
 - Issue #20635: Fixed grid_columnconfigure() and grid_rowconfigure() methods of
-- 
2.40.0