New submission from xiaobing jiang:
the inspect module leak docs. all these functions have no doc. getlineno getabsfile getblock formatannotation walktree findsource indentsize getargs formatannotationrelativeto classify_class_attrs
---------- assignee: docs@python components: Documentation messages: 189193 nosy: docs@python, s7v7nislands@gmail.com priority: normal severity: normal status: open title: inspect module leak docs type: enhancement versions: Python 3.3
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue17972 _______________________________________
Terry J. Reedy added the comment:
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.
---------- nosy: +terry.reedy stage: -> needs patch title: inspect module leak docs -> inspect module docs omits many functions
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue17972 _______________________________________
xiaobing jiang added the comment:
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!
----------
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue17972 _______________________________________
Changes by Eric Snow ericsnowcurrently@gmail.com:
---------- nosy: +eric.snow
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue17972 _______________________________________
Change by Martin Panter vadmium+py@gmail.com:
---------- dependencies: +Online doc does not include inspect.classify_class_attrs
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue17972 _______________________________________
Change by Terry J. Reedy tjreedy@udel.edu:
---------- type: enhancement -> behavior versions: +Python 3.7 -Python 3.3
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue17972 _______________________________________
Change by Anand Reddy Pandikunta anand21nanda@gmail.com:
---------- nosy: +chillaranand
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue17972 _______________________________________
Change by Cheryl Sabella chekat2@gmail.com:
---------- dependencies: -Online doc does not include inspect.classify_class_attrs keywords: +easy
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue17972 _______________________________________
Paul Rudin paul@rudin.co.uk added the comment:
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).
---------- nosy: +PaulRudin
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue17972 _______________________________________
R. David Murray rdmurray@bitdance.com added the comment:
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?
---------- nosy: +r.david.murray
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue17972 _______________________________________
Paul Rudin paul@rudin.co.uk added the comment:
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.
----------
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue17972 _______________________________________
R. David Murray rdmurray@bitdance.com added the comment:
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.
----------
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue17972 _______________________________________
Paul Rudin paul@rudin.co.uk added the comment:
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.
----------
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue17972 _______________________________________
Matthias Bussonnier bussonniermatthias@gmail.com added the comment:
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__`.
---------- nosy: +mbussonn
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue17972 _______________________________________
Change by Matthias Bussonnier bussonniermatthias@gmail.com:
---------- keywords: +patch pull_requests: +6644 stage: needs patch -> patch review
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue17972 _______________________________________
Change by Karthikeyan Singaravelan tir.karthi@gmail.com:
---------- nosy: +xtreak
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue17972 _______________________________________
Lysandros Nikolaou lisandrosnik@gmail.com added the comment:
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?
---------- nosy: +lys.nikolaou
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue17972 _______________________________________
Lysandros Nikolaou lisandrosnik@gmail.com added the comment:
...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*.
----------
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue17972 _______________________________________
Cheryl Sabella cheryl.sabella@gmail.com added the comment:
issue12317 discusses inspect.getabsfile()
---------- nosy: +cheryl.sabella
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue17972 _______________________________________
Change by kernc kerncece@gmail.com:
---------- nosy: +kernc
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue17972 _______________________________________
participants (12)
-
Anand Reddy Pandikunta -
Cheryl Sabella
-
Eric Snow
-
Karthikeyan Singaravelan
-
kernc
-
Lysandros Nikolaou
-
Martin Panter
-
Matthias Bussonnier
-
Paul Rudin
-
R. David Murray
-
Terry J. Reedy
-
xiaobing jiang