Re: [Python-Dev] readonly __doc__
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 | ncogh...@gmail.com | Brisbane, Australia --- ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] readonly __doc__
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. -- Steven D'Aprano ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] readonly __doc__
Le jeudi 22 octobre 2009 à 13:59 -0700, Guido van Rossum a écrit : > > I don't really understand how this explains the read-only __doc__. > > I am talking about modifying __doc__ on a class, not on an instance. > > (sure, a new-style class is also an instance of type, but still...) > > Antoine, it's not clear from the questions you're asking whether > you've read the code in typobject.c that implements __doc__ or not. Ah, well I haven't :-/ My bad. Regards Antoine. ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] readonly __doc__
On Thu, Oct 22, 2009 at 1:49 PM, Antoine Pitrou wrote: > Brett Cannon python.org> writes: >> 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. > > I don't really understand how this explains the read-only __doc__. > I am talking about modifying __doc__ on a class, not on an instance. > (sure, a new-style class is also an instance of type, but still...) Antoine, it's not clear from the questions you're asking whether you've read the code in typobject.c that implements __doc__ or not. -- --Guido van Rossum (home page: http://www.python.org/~guido/) ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] readonly __doc__
Brett Cannon python.org> writes: > > > 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. I don't really understand how this explains the read-only __doc__. I am talking about modifying __doc__ on a class, not on an instance. (sure, a new-style class is also an instance of type, but still...) Antoine. ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] readonly __doc__
On Oct 22, 2009, at 2:39 PM, Brett Cannon wrote: On Thu, Oct 22, 2009 at 11:18, sstein...@gmail.com > wrote: On Oct 22, 2009, at 1:58 PM, Guido van Rossum wrote: Well __doc__ isn't a normal attribute -- it doesn't follow inheritance rules. Maybe we could add a ticket to flag this in the docs. Sure, go for it. Filed: http://bugs.python.org/issue7186 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. It means, is it special because it's a "special" i.e. __X__ type attribute or because of something special about __doc__ itself, independent of it being a "special attribute". 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. Any others that deserve special notice, while we're at it? Don't know. Ok, issue recorded. Thanks, S ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] readonly __doc__
On Thu, Oct 22, 2009 at 11:18, sstein...@gmail.com wrote: > > On Oct 22, 2009, at 1:58 PM, Guido van Rossum wrote: > > Well __doc__ isn't a normal attribute -- it doesn't follow inheritance >> rules. >> > > Maybe we could add a ticket to flag this in the docs. > > Sure, go for it. > 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. > Any others that deserve special notice, while we're at it? > Don't know. ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] readonly __doc__
On Oct 22, 2009, at 1:58 PM, Guido van Rossum wrote: Well __doc__ isn't a normal attribute -- it doesn't follow inheritance rules. Maybe we could add a ticket to flag this in the docs. Is __doc__ not normal due to its general underscorishness, or is it not normal because it isn't? Any others that deserve special notice, while we're at it? Thanks, S ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] readonly __doc__
On Thu, Oct 22, 2009 at 1:25 PM, Antoine Pitrou wrote: .. > I might add why I was asking this question. I was trying to demonstrate the > use > of class decorators and the simplest example I found was to add a docstring to > the class. I always thought that read-only __doc__ was an artifact of new classes evolving from (C-implemented) types. IIRC, NumPy project implemented a somewhat elaborate hack to allow docstrings to be added to C-implemented classes in a .py file. ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] readonly __doc__
Well __doc__ isn't a normal attribute -- it doesn't follow inheritance rules. On Thu, Oct 22, 2009 at 10:25 AM, Antoine Pitrou wrote: > Guido van Rossum python.org> writes: >> >> On Thu, Oct 22, 2009 at 9:45 AM, Antoine Pitrou pitrou.net> > wrote: >> > >> > Speaking of the __doc__ property, I just noticed the following thing > on py3k: >> > >> class C: pass >> > ... >> C.__doc__ = "hop" >> > Traceback (most recent call last): >> > File "", line 1, in >> > AttributeError: attribute '__doc__' of 'type' objects is not writable >> > >> > Is this deliberate? >> >> Yes. > > I might add why I was asking this question. I was trying to demonstrate the > use > of class decorators and the simplest example I found was to add a docstring to > the class. And I was surprised when I saw the following fail with the > aforementioned exception: > > def classdeco(cls): > cls.__doc__ = "decorated!" > return cls > > @classdeco > class C: > pass > > > Regards > > Antoine. > > > ___ > Python-Dev mailing list > Python-Dev@python.org > http://mail.python.org/mailman/listinfo/python-dev > Unsubscribe: > http://mail.python.org/mailman/options/python-dev/guido%40python.org > -- --Guido van Rossum (home page: http://www.python.org/~guido/) ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] readonly __doc__
Guido van Rossum python.org> writes: > > On Thu, Oct 22, 2009 at 9:45 AM, Antoine Pitrou pitrou.net> wrote: > > > > Speaking of the __doc__ property, I just noticed the following thing on py3k: > > > class C: pass > > ... > C.__doc__ = "hop" > > Traceback (most recent call last): > > File "", line 1, in > > AttributeError: attribute '__doc__' of 'type' objects is not writable > > > > Is this deliberate? > > Yes. I might add why I was asking this question. I was trying to demonstrate the use of class decorators and the simplest example I found was to add a docstring to the class. And I was surprised when I saw the following fail with the aforementioned exception: def classdeco(cls): cls.__doc__ = "decorated!" return cls @classdeco class C: pass Regards Antoine. ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] readonly __doc__
On Thu, Oct 22, 2009 at 7:12 PM, Guido van Rossum wrote: > Yes. Why? --yuv ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] readonly __doc__
On Thu, Oct 22, 2009 at 9:45 AM, Antoine Pitrou wrote: > > Speaking of the __doc__ property, I just noticed the following thing on py3k: > class C: pass > ... C.__doc__ = "hop" > Traceback (most recent call last): > File "", line 1, in > AttributeError: attribute '__doc__' of 'type' objects is not writable > > Is this deliberate? Yes. -- --Guido van Rossum (home page: http://www.python.org/~guido/) ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] readonly __doc__
> Speaking of the __doc__ property, I just noticed the following thing on > py3k: > class C: pass > ... C.__doc__ = "hop" > Traceback (most recent call last): > File "", line 1, in > AttributeError: attribute '__doc__' of 'type' objects is not writable Happens also with new style classes in python 2.x: Python 2.5.1 (r251:54863, Oct 30 2007, 13:45:26) [GCC 4.1.2 20070925 (Red Hat 4.1.2-33)] on linux2 Type "help", "copyright", "credits" or "license" for more information. >>> class C(object): pass ... >>> C.__doc__ = 'hello' Traceback (most recent call last): File "", line 1, in AttributeError: attribute '__doc__' of 'type' objects is not writable >>> But not with old style classes: Python 2.5.1 (r251:54863, Oct 30 2007, 13:45:26) [GCC 4.1.2 20070925 (Red Hat 4.1.2-33)] on linux2 Type "help", "copyright", "credits" or "license" for more information. >>> class C: pass ... >>> C.__doc__ = 'hello' >>> Cheers, Daniel -- Psss, psss, put it down! - http://www.cafepress.com/putitdown ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
