[Python-Dev] readonly __doc__

[Nick Coghlan]

Steven D'Aprano wrote:
> 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 
> attributes.

This actually breaks a recipe I recently suggested in python-ideas,
where I recommended inheriting from a namedtuple instance in order to
insert additional argument validity checks in __new__.

Probably not invalid for it to break there though - in the case of that
recipe, the default docstring from the parent class really should be
replaced with one that details the additional constraints being placed
on the arguments. Then again, the parent class docstring wouldn't have
been wrong - merely incomplete.

The point you mentioned about doctests silently failing to run strikes
me as a pretty major glitch due to this behaviour though. Having a base
class that defines the doctests to run in its docstring and then
creating subclasses to specialise the test execution sounds like a
perfectly reasonable use case to me (even though I personally tend to
write unittest based test rather than doctest based ones).

Cheers,
Nick.

-- 
Nick Coghlan   |   ncoghlan at gmail.com   |   Brisbane, Australia
---------------------------------------------------------------