From 90b273021c4c00cfd48934088dce43553921a72b Mon Sep 17 00:00:00 2001 From: Matthias Bussonnier Date: Sat, 19 May 2018 15:22:22 -0700 Subject: [PATCH] bpo-17972: Document `findsource` in inspect.rst From the discussion in bpo-1792, it seem that findsource is mostly low level, while getsource is higher level. This does not completely fix bpo-17972 as many methonds need to be marked either private, or documented --- Doc/library/inspect.rst | 15 +++++++++++++++ .../2018-05-19-15-26-25.bpo-17972.eBXOAY.rst | 1 + 2 files changed, 16 insertions(+) create mode 100644 Misc/NEWS.d/next/Documentation/2018-05-19-15-26-25.bpo-17972.eBXOAY.rst diff --git a/Doc/library/inspect.rst b/Doc/library/inspect.rst index 7db6ca68b23ca0..2d92ae020e5860 100644 --- a/Doc/library/inspect.rst +++ b/Doc/library/inspect.rst @@ -511,10 +511,25 @@ Retrieving source code returned as a single string. An :exc:`OSError` is raised if the source code cannot be retrieved. + If *object* is a wrapper function (that is to say has a :attr:`__wrapped__` + field, :func:`getsource` will follows the chain of :attr:`__wrapped__` + attributes returning the last object in the chain using :func:`unwrap` + .. versionchanged:: 3.3 :exc:`OSError` is raised instead of :exc:`IOError`, now an alias of the former. +.. function:: findsource(object) + + Return the entire source file and starting line number for an object. + + The argument may be a module, class, method, function, traceback, frame, + or code object. The source code is returned as a list of all the lines + in the file and the line number indexes a line in that list. An OSError + is raised if the source code cannot be retrieved. + + Prefer the use of :func:`getsource` if possible. + .. function:: cleandoc(doc) diff --git a/Misc/NEWS.d/next/Documentation/2018-05-19-15-26-25.bpo-17972.eBXOAY.rst b/Misc/NEWS.d/next/Documentation/2018-05-19-15-26-25.bpo-17972.eBXOAY.rst new file mode 100644 index 00000000000000..ef6220c5593096 --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/2018-05-19-15-26-25.bpo-17972.eBXOAY.rst @@ -0,0 +1 @@ +Document :func:`inspect.findsource`