mirror of
https://github.com/wassname/segpy.git
synced 2026-07-15 11:26:04 +08:00
71 lines
1.8 KiB
Python
71 lines
1.8 KiB
Python
|
|
"""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() |