diff -r c8d8a6cc5586 Doc/library/inspect.rst --- a/Doc/library/inspect.rst Thu Apr 24 19:39:18 2014 -0400 +++ b/Doc/library/inspect.rst Tue Apr 29 17:33:54 2014 +0200 @@ -349,6 +349,12 @@ Python source file (if the object is a module). +.. function:: splitdoc(doc) + + Return a tuple where the first element is the synopsis of the function and the second + element is the rest of the documentation. + + .. function:: getfile(object) Return the name of the (text or binary) file in which an object was defined. diff -r c8d8a6cc5586 Lib/inspect.py --- a/Lib/inspect.py Thu Apr 24 19:39:18 2014 -0400 +++ b/Lib/inspect.py Tue Apr 29 17:33:54 2014 +0200 @@ -13,6 +13,7 @@ getfile(), getsourcefile(), getsource() - find an object's source code getdoc(), getcomments() - get documentation on an object + splitdoc() - split a doc strign into a synopsis line (if any) and the rest getmodule() - determine the module that an object came from getclasstree() - arrange classes so as to represent their hierarchy @@ -482,6 +483,15 @@ return None return cleandoc(doc) +def splitdoc(doc): + """Split a doc string into a synopsis line (if any) and the rest.""" + lines = doc.strip().split('\n') + if len(lines) == 1: + return lines[0], '' + elif len(lines) >= 2 and not lines[1].rstrip(): + return lines[0], '\n'.join(lines[2:]) + return '', '\n'.join(lines) + def cleandoc(doc): """Clean up indentation from docstrings. diff -r c8d8a6cc5586 Lib/pydoc.py --- a/Lib/pydoc.py Thu Apr 24 19:39:18 2014 -0400 +++ b/Lib/pydoc.py Tue Apr 29 17:33:54 2014 +0200 @@ -69,6 +69,8 @@ from reprlib import Repr from traceback import format_exception_only +from inspect import splitdoc # Backward compatiblity + # --------------------------------------------------------- common routines @@ -89,15 +91,6 @@ result = inspect.getdoc(object) or inspect.getcomments(object) return result and re.sub('^ *\n', '', result.rstrip()) or '' -def splitdoc(doc): - """Split a doc string into a synopsis line (if any) and the rest.""" - lines = doc.strip().split('\n') - if len(lines) == 1: - return lines[0], '' - elif len(lines) >= 2 and not lines[1].rstrip(): - return lines[0], '\n'.join(lines[2:]) - return '', '\n'.join(lines) - def classname(object, modname): """Get a class name and qualify it with a module name if necessary.""" name = object.__name__ @@ -1084,7 +1077,7 @@ def docmodule(self, object, name=None, mod=None): """Produce text documentation for a given module object.""" name = object.__name__ # ignore the passed-in name - synop, desc = splitdoc(getdoc(object)) + synop, desc = inspect.splitdoc(getdoc(object)) result = self.section('NAME', name + (synop and ' - ' + synop)) all = getattr(object, '__all__', None) docloc = self.getdocloc(object) diff -r c8d8a6cc5586 Lib/test/test_inspect.py --- a/Lib/test/test_inspect.py Thu Apr 24 19:39:18 2014 -0400 +++ b/Lib/test/test_inspect.py Tue Apr 29 17:33:54 2014 +0200 @@ -280,6 +280,16 @@ self.assertEqual(inspect.getdoc(git.abuse), 'Another\n\ndocstring\n\ncontaining\n\ntabs') + def test_splitdoc(self): + from pydoc import getdoc + + self.assertEqual(inspect.splitdoc(getdoc(mod)), + ('A module docstring.', '')) + + self.assertEqual(inspect.splitdoc(getdoc(mod.StupidGit)), + ('A longer,', 'indented\n\ndocstring.')) + + def test_cleandoc(self): self.assertEqual(inspect.cleandoc('An\n indented\n docstring.'), 'An\nindented\ndocstring.') diff -r c8d8a6cc5586 Lib/test/test_pydoc.py --- a/Lib/test/test_pydoc.py Thu Apr 24 19:39:18 2014 -0400 +++ b/Lib/test/test_pydoc.py Tue Apr 29 17:33:54 2014 +0200 @@ -402,6 +402,13 @@ result, doc_loc = get_pydoc_text(xml.etree) self.assertEqual(doc_loc, "", "MODULE DOCS incorrectly includes a link") + def test_issue12916(self): + # Test issue12916 to ensure we will remove the pydoc.splitdoc in 3.7 + splitdoc = getattr(pydoc, 'splitdoc', None) + if splitdoc and sys.version_info >= (3, 7): + self.fail("pydoc.splitdoc() is deprecated since 3.5, " + "you must to remove it in 3.7 and use inspect.splitdoc()") + def test_non_str_name(self): # issue14638 # Treat illegal (non-str) name like no name