diff -r 08c8d492f46d Doc/library/inspect.rst --- a/Doc/library/inspect.rst Sat Oct 11 14:32:23 2014 +0100 +++ b/Doc/library/inspect.rst Sat Oct 11 14:39:20 2014 +0100 @@ -365,6 +365,14 @@ 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. + + .. versionadded:: 3.5 + + .. function:: getfile(object) Return the name of the (text or binary) file in which an object was defined. diff -r 08c8d492f46d Doc/whatsnew/3.5.rst --- a/Doc/whatsnew/3.5.rst Sat Oct 11 14:32:23 2014 +0100 +++ b/Doc/whatsnew/3.5.rst Sat Oct 11 14:39:20 2014 +0100 @@ -203,6 +203,10 @@ subclassing of :class:`~inspect.Signature` easier (contributed by Yury Selivanov and Eric Snow in :issue:`17373`). +* New function :func:`inspect.splitdoc`, which returns a tuple from a + documentation where the first element is the synopsis of the function and the + second element is the rest of the documentation. + ipaddress --------- diff -r 08c8d492f46d Lib/inspect.py --- a/Lib/inspect.py Sat Oct 11 14:32:23 2014 +0100 +++ b/Lib/inspect.py Sat Oct 11 14:39:20 2014 +0100 @@ -13,6 +13,7 @@ getfile(), getsourcefile(), getsource() - find an object's source code getdoc(), getcomments() - get documentation on an object + splitdoc() - split a doc string 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,18 @@ return None return cleandoc(doc) +def splitdoc(doc): + """Split a doc string into a synopsis line (if any) and the rest.""" + if not isinstance(doc, str): + raise TypeError("doc must be a string") + + 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 08c8d492f46d Lib/pydoc.py --- a/Lib/pydoc.py Sat Oct 11 14:32:23 2014 +0100 +++ b/Lib/pydoc.py Sat Oct 11 14:39:20 2014 +0100 @@ -69,6 +69,7 @@ from collections import deque from reprlib import Repr from traceback import format_exception_only +import inspect # --------------------------------------------------------- common routines @@ -91,13 +92,14 @@ 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) + """**DEPRECATED** + + Split a doc string into a synopsis line (if any) and the rest. + """ + warnings.warn("the pydoc.splitdoc is deprecated in favour " + "of inspect.splitdoc", + PendingDeprecationWarning) + return inspect.splitdoc(doc) def classname(object, modname): """Get a class name and qualify it with a module name if necessary.""" diff -r 08c8d492f46d Lib/test/test_inspect.py --- a/Lib/test/test_inspect.py Sat Oct 11 14:32:23 2014 +0100 +++ b/Lib/test/test_inspect.py Sat Oct 11 14:39:20 2014 +0100 @@ -289,6 +289,19 @@ self.assertEqual(inspect.getdoc(git.abuse), 'Another\n\ndocstring\n\ncontaining\n\ntabs') + def test_splitdoc(self): + from pydoc import getdoc + + with self.assertRaises(TypeError): + inspect.splitdoc(None) + + 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 08c8d492f46d Lib/test/test_pydoc.py --- a/Lib/test/test_pydoc.py Sat Oct 11 14:32:23 2014 +0100 +++ b/Lib/test/test_pydoc.py Sat Oct 11 14:39:20 2014 +0100 @@ -439,6 +439,14 @@ finally: sys.stdin = previous_stdin + 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