3

When the python help function is invoked with an argument of string type, it is interpreted by pydoc.Helper.help as a request for information on the topic, symbol, keyword or module identified by the value of the string. For other arguments, help on the object itself is provided, unless the object is an instance of a subclass of str. In this latter case, the pydoc.resolve function looks for a module with a name matching the value of the object and raises an exception if none is found.

To illustrate this, consider the example code:

class Extra(object): 
       def NewMethod(): return 'New' 
Cls1 = type( 'FirstClass', (str,Extra), {'__doc__':'My new class','extra':'An extra attribute'})
inst1 = Cls1('METHODS')
help( 'METHODS' )
help( inst1 )

The first invocation of help produces information on the topic "METHODS", the 2nd produces an error message because the pydoc.resolve function is trying to find a module called "METHODS".

This means that it is difficult to provide effective documentation for user defined sub-classes of str. Would it not be possible for pydoc.resolve to use a test on the type of the object, as is done in pydoc.Helper.help, and allow instances of user defined sub-classes to be treated as other class instances?

This question follows from earlier discussion of a related question here.

M Juckes
  • 299
  • 1
  • 6
  • Probably when all this machinery was written, it wasn't even possible to subclass built-in types in python. It is now possible, but generally not something you see, especially not for basic types like `str` and `int` – juanpa.arrivillaga Dec 23 '19 at 21:26

1 Answers1

0

The simple answer is that making user-defined subclasses of str is not the most common case—partly because the user-defined data but not the string data would be mutable. By the time you have to deal with such, it’s imagined that you know how to write help(type(x)), and using isinstance rather than type(…) is … is the correct default in general. (The other way, you’d have to use help(str(x)) if you wanted to use it, like any other string, to select a help topic, but that’s surely even rarer.)

Davis Herring
  • 36,443
  • 4
  • 48
  • 76
  • Thanks, the tip to use `help(type(x))` is useful. Can you say where that is documented? – M Juckes Dec 25 '19 at 00:13
  • @user3540774: It’s implied by statements like “Use help(str) to get help on the str class.” and anything like `help(socket.socket)` where you might not know how to make one yet. – Davis Herring Dec 25 '19 at 00:36
  • That doesn't explain why an instance of a sub-class of str is treated differently from an instance of str. – M Juckes Jan 15 '20 at 16:17
  • @user3540774: They’re not treated differently; that’s the whole issue. – Davis Herring Jan 15 '20 at 16:23
  • 1
    They are treated differently, that is the point of the question. In the example given above, `help( "METHODS" )` and `help( Cls1("METHODS") )` give different responses. The first gives help on the "METHODS" topic, the 2nd gives "No Python documentation found for 'METHODS'." – M Juckes Jan 16 '20 at 13:50
  • @user3540774: Yes, sorry. There are *three* different choices here: look up a *topic*, look up a *name*, and describe the (type of the) *object*. I answered why `help(Cls1("…"))` doesn’t do the last, while you’re asking why it doesn’t do the first. I think the additional answer is just that no one thought about subclasses very much. – Davis Herring Jan 16 '20 at 15:38