[Python-Dev] readonly doc (original) (raw)

Nick Coghlan ncoghlan at gmail.com
Fri Oct 23 11:46:00 CEST 2009

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

More information about the Python-Dev mailing list