Skip to content

Instantly share code, notes, and snippets.

Embed
What would you like to do?
Property decorator for the `__doc__` attribute.
"""Property decorator for the `__doc__` attribute.
Useful for when you want a custom docstring for class instances
while still showing a generic docstring for the class itself.
A naive attempt using `@property` generally breaks Sphinx as
`cls.__doc__` returns the property object itself, and not a string.
See the documentation for `docstring_property` for an example.
"""
def docstring_property(class_doc):
"""Property attribute for docstrings.
Usage
-----
>>> class A(object):
... '''Main docstring'''
... def __init__(self, x):
... self.x = x
... @docstring_property(__doc__)
... def __doc__(self):
... return "My value of x is %s." % self.x
>>> A.__doc__
'Main docstring'
>>> a = A(10)
>>> a.__doc__
'My value of x is 10.'
"""
def wrapper(fget):
return DocstringProperty(class_doc, fget)
return wrapper
class DocstringProperty(object):
"""Property for the `__doc__` attribute.
Different than `property` in the following two ways:
* When the attribute is accessed from the main class, it returns the value
of `class_doc`, *not* the property itself. This is necessary so Sphinx
and other documentation tools can access the class docstring.
* Only supports getting the attribute; setting and deleting raise an
`AttributeError`.
"""
def __init__(self, class_doc, fget):
self.class_doc = class_doc
self.fget = fget
def __get__(self, obj, type=None):
if obj is None:
return self.class_doc
else:
return self.fget(obj)
def __set__(self, obj, value):
raise AttributeError("can't set attribute")
def __delete__(self, obj):
raise AttributeError("can't delete attribute")
if __name__ == "__main__":
import doctest
doctest.testmod()
@lgautier

This comment has been minimized.

Copy link

commented Sep 23, 2013

Nice.
(and working with Python 2.7 and 3.3)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.