Why does the Python help function applied to an instance return a page about the parent class in some cases and not it others?

Question

I'm trying to understand how to get useful results when the help function is used to interrogate objects created in my code. I'm puzzled by different behavior for different classes.

Cls1 = type( 'FirstClass', (str,), {'__doc__':'My new class'})
inst1 = Cls1('Hello World')

Cls2 = type( 'SecondClass', (object,), {'__doc__':'My second new class'})
inst2 = Cls2( )

help(inst1) yields No Python documentation found for 'Hello World', while help(inst2) yields:

Help on SecondClass in module __main__ object:

class SecondClass(builtins.object)
 |  My second new class
 |  
...

I would like to create a class based on str and be able to have useful messages displayed by the help function: is there a simple way of achieving this?

Answer 1

If you want to create a subclass of str and show the hints with help built-in, you can use docstrings. For instance the following subclass

class NewString(str):
    """This is a brand new implementation of string type"""
    def test_method(self):
        """This is a test method in the new implementation"""
        pass

has the following output on help(NewString)

class NewString(builtins.str)
 |  This is a brand new implementation of string type
 |  
 |  Method resolution order:
 |      NewString
 |      builtins.str
 |      builtins.object
 |  
 |  Methods defined here:
 |  
 |  test_method(self)
 |      This is a test method in the new implementation
...

But as for all instances of string the help method will not be useful.

The reason it fails is that when passing a str to help build-in it is treated as the name of a function, and as there obviously is not a function named Hello World it shows an error.

Running the following help('help') will output:

Help on _Helper in module _sitebuiltins object:

help = class _Helper(builtins.object)
 |  Define the builtin 'help'.
 |  
 |  This is a wrapper around pydoc.help that provides a helpful message
 |  when 'help' is typed at the Python interactive prompt.
 |  
 |  Calling help() at the Python prompt starts an interactive help session.
 |  Calling help(thing) prints help for the python object 'thing'.
...

which is the help on help.