9

I have seen the following statement in a number of docstrings when help()ing a class: "See help(type(self)) for accurate signature."

Notably, it is in the help() for scipy.stats.binom.__init__ and for stockfish.Stockfish.__init__ at the very least. I assume, therefore, that it is some sort of stock message.

In any case, I can't figure out what the heck it means. Is this useful information? Note that, being "outside" of the class, so to speak, I never have access to self. Furthermore, it is impossible to instantiate a class if I cannot access the signature of the __init__ method, and can therefore not even do help(type(my_object_instantiated)). Its a catch 22. In order to use __init__, I need the signature for __init__, but in order to read the signature for __init__, I need to instantiate an object with __init__. This point is strictly academic however, for even when I do manage to instantiate a scipy.stats.binom, it actually returns an object of an entirely different class, rv_frozen, with the exact same message in its __init__ docstring, but whose signature is entirely different and entirely less useful. In other words, help(type(self)) actually does not give an accurate signature. It is useless.

Does anyone know where this message comes from, or what I'm supposed to make of it? Is it just stock rubbish from a documentation generator, or am I user-erroring?

Him
  • 5,257
  • 3
  • 26
  • 83
  • You don't need to instantiate an object, you just need to know its class, so you can write `help(scipy.stats.binom)` – Barmar Jan 09 '19 at 16:36
  • @Barmar, that is precisely the call to `help` that gives the cryptic docstring “See help(type(self)) for accurate signature.” (under the `__init__` method) – Him Jan 09 '19 at 17:15
  • 1
    I found `See help(type(self)) for accurate signature.` here: https://github.com/python/cpython/blob/master/Lib/idlelib/idle_test/test_calltip.py#L71. This looks like test code for IDLE. I cannot explain how that string ends up in docstrings in various libraries. – mzjn Jan 09 '19 at 17:28

1 Answers1

4

There is a convention that the signature for constructing a class instance is put in the __doc__ on the class (since that is what the user calls) rather than on __init__ (or __new__) which determines that signature. This is especially true for extension types (written in C) whose __init__ cannot have its signature discovered via introspection.

The message that you see is part of the type class (see help(type.__init__)) and is thus inherited by metaclasses by default.

In some versions, scipy.stats.binom confuses the matter by not actually being a type; it is merely an instance of another class that (like type) is callable. So asking for help on it merely gives the help for that class (just like help(1) gets you help(int))—you have to look at its __call__ for further information (if any). And asking for help on the result of calling it gives you help for the actual class of whatever it returns, as you observed.

Davis Herring
  • 36,443
  • 4
  • 48
  • 76