[issue21309] Confusing "see also" for generic C-level __init__ methods in help output

[Larry Hastings]

Change by Larry Hastings :


--
nosy:  -larry

___
Python tracker 

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

[issue21309] Confusing "see also" for generic C-level __init__ methods in help output

[Irit Katriel]

Irit Katriel  added the comment:

Still the same in 3.10:

Python 3.10.0a5+ (heads/master:bf2e7e55d7, Feb 11 2021, 23:09:25) [MSC v.1928 
64 bit (AMD64)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>> help(ImportError.__init__)
Help on wrapper_descriptor:

__init__(self, /, *args, **kwargs)
Initialize self.  See help(type(self)) for accurate signature.

--
nosy: +iritkatriel
versions: +Python 3.10 -Python 3.5

___
Python tracker 

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

[issue21309] Confusing see also for generic C-level __init__ methods in help output

[R. David Murray]

R. David Murray added the comment:

I'm hoping that with Argument Clinic we can do better, but I haven't played 
with it so I'm not sure.

--

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

[issue21309] Confusing see also for generic C-level __init__ methods in help output

[Jacob Beck]

Jacob Beck added the comment:

I just got burned by this in io.StringIO, so I did a bit of looking.


This was changed in r85710aa396ef in Objects/typeobject.c. The new revision 
makes as much sense as the old one, which wasn't helpful either and replaced an 
equally unhelpful revision at some point. Some variation of this goes back at 
least as far back as Python2.5, which is the oldest version I have installed on 
my machine.


I think the real problem with this is what you touched on in the middle there. 
It frequently shows up on types that *don't* provide an accurate signature in 
their docstring or help(). For instance, io.StringIO doesn't discuss its 
signature at all, you have to look in the docs for the io module itself! I only 
figured that out after searching for it online. I think the entire exception 
hierarchy does it. At least in some of the more complicated exceptions you can 
sort of infer the arguments from the order in which the data descriptors are 
listed.

Based on where the message comes from I'm not sure how one could fix this. It's 
not clear to me that the type name is really available when this string is 
being calculated, since it's just a default docstring. The easiest fix might be 
something like Initializes an object. There is no information about this 
method's call signature, help for the class may describe it. Or maybe it would 
be possible to write actual __init__ docstrings for some or all of the classes 
involved?

--
nosy: +Jacob.Beck

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

[issue21309] Confusing see also for generic C-level __init__ methods in help output

[R. David Murray]

New submission from R. David Murray:

 help(ImportError.__init__)
Help on wrapper_descriptor:

__init__(self, /, *args, **kwargs)
Initialize self.  See help(type(self)) for accurate signature.

The above also appears (without the wrapper_descriptor bit) in the help output 
for help(ImportError).  In neither case does 'help(type(self))' tell the naive 
user anything useful, since 'self' doesn't exist in the scope in which they are 
executing help.  I don't know where this text is coming from (Argument 
Clinic?), but it could use improvement.  I believe it is trying to say that one 
should see the help information for the class object.  I'm not sure how you'd 
spell that usefully.  Maybe See the object's main help for a more accurate 
signature?

And maybe I shouldn't have said naive user: I'm an experienced python 
developer, and I tried 'help(type(ImportError))', since I saw the above when 
I'd typed 'help(ImportError)', and it was only when I got the help for 'type' 
that I realized what it was trying to tell me.  Now, I tried this because the 
ImportError help does not in fact give the more accurate signature, which is 
a different issue, but you get the point.  

We also have:

 x = ImportError()
 help(x.__init__)
Help on method-wrapper object:

__init__ = class method-wrapper(object)
 |  Methods defined here:
 |  
 |  __call__(self, /, *args, **kwargs)
 |  Call self as a function.

Maybe that's another bug?  Maybe not.

NB: in 3.3 the text is:

  |  __init__(...)
  |  x.__init__(...) initializes x; see help(type(x)) for signature

So that was worse, since the only time you would see in isolation would be when 
you are calling help on the class (help(ImportError.__init__)...in which case 
'x' is ImportError, and type(x) is...type.  So 3.4 is *better*, but I don't 
think it is as good as we can do.

--
components: Interpreter Core
messages: 216836
nosy: larry, r.david.murray
priority: normal
severity: normal
status: open
title: Confusing see also for generic C-level __init__ methods in help output
type: enhancement
versions: Python 3.5

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