classification
Title: inspect module docs omits many functions
Type: behavior Stage: patch review
Components: Documentation Versions: Python 3.7
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: PaulRudin, chillaranand, docs@python, eric.snow, lys.nikolaou, mbussonn, r.david.murray, s7v7nislands@gmail.com, terry.reedy, xtreak
Priority: normal Keywords: easy, patch

Created on 2013-05-14 03:11 by s7v7nislands@gmail.com, last changed 2018-11-13 13:08 by lys.nikolaou.

Pull Requests
URL Status Linked Edit
PR 6992 open mbussonn, 2018-05-19 22:31
Messages (11)
msg189193 - (view) Author: xiaobing jiang (s7v7nislands@gmail.com) Date: 2013-05-14 03:11
the inspect module leak docs.
all these functions have no doc.
getlineno
getabsfile
getblock
formatannotation
walktree
findsource
indentsize
getargs
formatannotationrelativeto
classify_class_attrs
msg189308 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2013-05-15 21:23
I do not know what you mean by 'leak docs' so I changed the title to something that makes more sense. It is possible that these functions are considered private to the module, but then their names should be preceded by '_', or else there should be an '__all__' list that omits them. So the omission may be a mistake. I do not know.
msg189337 - (view) Author: xiaobing jiang (s7v7nislands@gmail.com) Date: 2013-05-16 02:33
when I read the memory_profiler source code, I find it using inspect.getblock(). so I check the doc, but can't find the function's doc. 

these functions are found not in doc. I want to known which function should in doc or not? in inspect module has no __all__ variable.

sorry for poor english!
msg309455 - (view) Author: Paul Rudin (PaulRudin) * Date: 2018-01-04 07:51
If some are to be considered private then the questions are: which ones and how to fix. Presumably renaming to start with "_" might break existing code, so maybe adding an __all__, and just including the public objects is better? That could break code existing relying on * imports I suppose. Deprecation is another possibility, although feels a little odd for things never documented.

formatannotation and formatannotationrelativeto look like a helper functions for formatargspec and are probably not intended as part of the public interface.

Similarly walktree looks like a helper for getclasstree (and its docstring describes it as such).
msg309466 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2018-01-04 14:09
I think adding an __all__ in 3.7 would be reasonable.  You are right that we can't simply rename them for backward compatibility reasons.  We could rename them, and leave a stub function (that calls the renamed function) but issues a deprecation warning.  We've done that for other old internal APIs that we wanted to mark as private elsewhere in the stdlib.  The question is, is it worth the trouble to do it?
msg309496 - (view) Author: Paul Rudin (PaulRudin) * Date: 2018-01-05 09:50
Documenting and generating a deprecation warning also makes them part of the documented public api. Or are you suggesting just the warning without including in the documentation?

Incidentally, there are also the classes BlockFinder and EndOfBlock, which are helpers for getblock and presumably not intended for public consumption.
msg309507 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2018-01-05 14:24
Just warnings, no docs.  We've done this before for other helper functions, but it is always a judgement call whether it is worth the churn.  I defer to those people who have actually done work on the module for the answer to that question.
msg309915 - (view) Author: Paul Rudin (PaulRudin) * Date: 2018-01-14 09:31
Although formatannotation is undocumented, its actually documented as a default value for one of the parameters of formatargspec, so it does form part of the module's public interface. However formatargspec is deprecated, so it's still OK to deprecate formatannotation.

formatannotation is also used as a helper within Parameter, which isn't deprecated, but the public interface or docs of Parameter don't mention formatannotation, so using _formatannotation instead is fine.

Since I've looked through this and, as far as I can tell, nobody is working on it, I'll make the changes and make a PR.
msg317141 - (view) Author: Matthias Bussonnier (mbussonn) * Date: 2018-05-19 22:18
Just came across the same issue.

It think that the exact behavior may depend on  functions. IT is also unclear when to use what sometime. 

For example, `getsource` seem to be preferable to findsource, getsource cannot be use to get the source of wrapping function as it follows `__wrapped__`.
msg329837 - (view) Author: Lysandros Nikolaou (lys.nikolaou) * Date: 2018-11-13 13:06
I think this issue should be discussed once more. I am not sure it's worth defining __all__, but then we would have to include them in the docs. If you think __all__ should be defined instead, then I could go through the trouble of doing so. Could a core developer maybe offer their opinion here?
msg329838 - (view) Author: Lysandros Nikolaou (lys.nikolaou) * Date: 2018-11-13 13:08
...but then we would have to include them in the docs... should be *but then we would have to include all the public functions in the docs*.
History
Date User Action Args
2018-11-13 13:08:23lys.nikolaousetmessages: + msg329838
2018-11-13 13:06:07lys.nikolaousetnosy: + lys.nikolaou
messages: + msg329837
2018-11-07 06:27:32xtreaksetnosy: + xtreak
2018-05-19 22:31:14mbussonnsetkeywords: + patch
stage: needs patch -> patch review
pull_requests: + pull_request6644
2018-05-19 22:18:20mbussonnsetnosy: + mbussonn
messages: + msg317141
2018-01-14 09:31:14PaulRudinsetmessages: + msg309915
2018-01-05 14:24:19r.david.murraysetmessages: + msg309507
2018-01-05 09:50:48PaulRudinsetmessages: + msg309496
2018-01-04 14:09:33r.david.murraysetnosy: + r.david.murray
messages: + msg309466
2018-01-04 07:51:33PaulRudinsetnosy: + PaulRudin
messages: + msg309455
2017-12-22 21:59:56cheryl.sabellasetkeywords: + easy
dependencies: - Online doc does not include inspect.classify_class_attrs
2017-12-22 21:59:13cheryl.sabellalinkissue32261 superseder
2017-12-21 14:55:31chillaranandsetnosy: + chillaranand
2017-12-16 03:39:59terry.reedysettype: enhancement -> behavior
versions: + Python 3.7, - Python 3.3
2017-12-10 02:38:07martin.pantersetdependencies: + Online doc does not include inspect.classify_class_attrs
2013-08-21 19:30:44eric.snowsetnosy: + eric.snow
2013-05-16 02:33:23s7v7nislands@gmail.comsetmessages: + msg189337
2013-05-15 21:23:42terry.reedysetnosy: + terry.reedy
title: inspect module leak docs -> inspect module docs omits many functions
messages: + msg189308

stage: needs patch
2013-05-14 03:11:08s7v7nislands@gmail.comcreate