[Python-Dev] readonly __doc__

Steven D'Aprano steve at pearwood.info
Fri Oct 23 04:13:55 CEST 2009

On Fri, 23 Oct 2009 05:39:53 am Brett Cannon wrote:

> > Is __doc__ not normal due to its general underscorishness, or is it
> > not normal because it isn't?
> I honestly don't follow that sentence. But __doc__ is special because
> of its use; documenting how to use of an object. In this case when
> you call something like help() on an instance of an object it skips
> the instance's value for __doc__ and goes straight to the defining
> class and stops there as you don't care how a subclass says to use
> itself as that is not what you are working with.

Classes don't normally inherit behaviour from their subclasses. 
Presumably you meant superclass.

I expected __doc__ to be just like the other double-underscore objects: 
lookup skips the instance and goes to the class, then follows the 
normal rules of inheritance. Consequently I've just discovered that a 
few of my classes, which I assumed inherited __doc__, don't actually 
have a docstring. This has consequences beyond help(obj) not working as 
expected: doctests which I thought were running aren't.

Magic behaviour like this is nasty because it breaks the Rule of Least 
Astonishment. I thought I understood Python's object model and it's 
rules of inheritance, but not only do double-underscore attributes 
follow a different rule for inheritance than other attributes, but 
__doc__ follows a different rule than other double-underscore 

Steven D'Aprano

More information about the Python-Dev mailing list