| 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) *  |
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) * |
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) * |
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*. |
|
|
| msg332167 - (view) |
Author: Cheryl Sabella (cheryl.sabella) * |
Date: 2018-12-19 22:23 |
| discusses inspect.getabsfile() |
|
|