Skip to content

Instantly share code, notes, and snippets.

Created November 8, 2012 19:35
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
Star You must be signed in to star a gist
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.
>>> 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
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
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
Copy link

(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