On Fri, Jun 10, 2011 at 11:45 AM, Eric Snow wrote:

...

Agreed that docstrings should be writeable after the fact, though (e.g. functions already work that way - functools.wraps wouldn't work otherwise).

Would this be a very controversial change?  I ask because it's been this way since 2.2 and no one's changed it.  Thanks.

More likely a matter of nobody needing the functionality enough to question the behaviour (there are a variety of arbitrary restrictions still floating around that don't really have a *reason*, it's just that it was easier to do it that way initially and nobody has cared enough to change it). Cheers, Nick. -- Nick Coghlan   |   ncoghlan@gmail.com   |   Brisbane, Australia

On Fri, Jun 10, 2011 at 5:04 PM, Greg Ewing wrote:

Nick Coghlan wrote:

...

-1. Subclasses are not the same thing as the original class so docstring inheritance should be requested explicitly.

The docstring of the class itself probably shouldn't be inherited automatically. But if you override a method without changing the API or user-visible behaviour, the inherited docstring still applies.

I believe Eric created a class decorator recipe on the cookbook site that does exactly that for methods without their own docstrings. Cheers, Nick. -- Nick Coghlan   |   ncoghlan@gmail.com   |   Brisbane, Australia

On Fri, Jun 10, 2011 at 3:28 AM, Arnaud Delobelle wrote:

Given that Python supports multiple inheritance, which parent class's __doc__ would the __basedoc__ contain?  Also, what would the __basedoc__ contain if the parent's __doc__ is empty but not its __basedoc__?

You would not need a __basedoc__ magic attribute, you can just do class C(object): pass docs = [c.__doc__ for c in C.__mro__] and you get the docs for all bases in the proper mro order Though I guess __basedocs__ mapping to [c.__doc__ for c in C.__mro__ if c != C] could be handy

David Stanek wrote:

On Fri, Jun 10, 2011 at 3:04 AM, Greg Ewing wrote:

...

Maybe the best thing would be for the inherited docstring to get put into a different property, such as __basedoc__. Then tools that examine docstrings can decide for themselves whether using inherited docstrings makes sense.

How would a tool know if the behavior of a method changed without analyzing the code? I think this could very easily lead to a situation where a project's generated documentation is incorrect.

That's the developer's problem, and no different from any other case where you inherit data without ensuring it is the correct data. class Parrot: colour = 'green' def speak(self): return "Polly wants a cracker." class NorwegianBlue(Parrot): def speak(self): return "I'm pining for the fjords." assert NorwegianBlue().colour == 'blue' # oops! -- Steven

David Stanek wrote:

On Fri, Jun 10, 2011 at 7:22 AM, Steven D'Aprano wrote:

...

David Stanek wrote:

...

How would a tool know if the behavior of a method changed without analyzing the code? I think this could very easily lead to a situation where a project's generated documentation is incorrect.

That's the developer's problem, and no different from any other case where you inherit data without ensuring it is the correct data.

This means that a significant amount of existing code may/will have problems with this type of change. If Sphinx did this automatically I'm sure there would be lots of incorrect documentation. I think the developer should explicitly carry over and modify the documentation if necessary.

Oh, I'm sorry if I gave the impression that we should inherit docstrings by default. That wasn't my intention. I was merely suggesting that we shouldn't let the risk of misuse discourage us from a potential change. -- Steven