[issue17972] inspect module docs omits many functions

[kernc]

Change by kernc :


--
nosy: +kernc

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue17972] inspect module docs omits many functions

[Cheryl Sabella]

Cheryl Sabella  added the comment:

issue12317 discusses inspect.getabsfile()

--
nosy: +cheryl.sabella

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue17972] inspect module docs omits many functions

[Lysandros Nikolaou]

Lysandros Nikolaou  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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue17972] inspect module docs omits many functions

[Lysandros Nikolaou]

Lysandros Nikolaou  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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue17972] inspect module docs omits many functions

[Karthikeyan Singaravelan]

Change by Karthikeyan Singaravelan :


--
nosy: +xtreak

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue17972] inspect module docs omits many functions

[Matthias Bussonnier]

Change by Matthias Bussonnier :


--
keywords: +patch
pull_requests: +6644
stage: needs patch -> patch review

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue17972] inspect module docs omits many functions

[Matthias Bussonnier]

Matthias Bussonnier  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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue17972] inspect module docs omits many functions

[Paul Rudin]

Paul Rudin  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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue17972] inspect module docs omits many functions

[R. David Murray]

R. David Murray  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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue17972] inspect module docs omits many functions

[Paul Rudin]

Paul Rudin  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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue17972] inspect module docs omits many functions

[R. David Murray]

R. David Murray  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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue17972] inspect module docs omits many functions

[Paul Rudin]

Paul Rudin  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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue17972] inspect module docs omits many functions

[Cheryl Sabella]

Change by Cheryl Sabella :


--
dependencies:  -Online doc does not include inspect.classify_class_attrs
keywords: +easy

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue17972] inspect module docs omits many functions

[Anand Reddy Pandikunta]

Change by Anand Reddy Pandikunta :


--
nosy: +chillaranand

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue17972] inspect module docs omits many functions

[Terry J. Reedy]

Change by Terry J. Reedy :


--
type: enhancement -> behavior
versions: +Python 3.7 -Python 3.3

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue17972] inspect module docs omits many functions

[Martin Panter]

Change by Martin Panter :


--
dependencies: +Online doc does not include inspect.classify_class_attrs

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue17972] inspect module docs omits many functions

[Eric Snow]

Changes by Eric Snow :


--
nosy: +eric.snow

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue17972] inspect module docs omits many functions

[xiaobing jiang]

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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue17972] inspect module docs omits many functions

[Terry J. Reedy]

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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com