实现保留文档字符串的类属性 [英] Implementing a class property that preserves the docstring

问题描述

我有一个描述符，可将方法转换为类级别的属性：

I have a descriptor that turns a method into a property on the class level:

class classproperty(object):

    def __init__(self, getter):
        self.getter = getter
        self.__doc__ = getter.__doc__

    def __get__(self, instance, owner):
        return self.getter(owner)

使用如下：

class A(object):
    @classproperty
    def test(cls):
        "docstring"
        return "Test"

但是，我现在无法访问 __ doc __ 属性（这是逻辑上的，因为访问 A.test .__ doc __ 将获取 __ doc __ str 中的$ c>，因为 A.test 已经返回 Test 。

However, I now can't access the __doc__ attribute (which is logical, because accessing A.test.__doc__ will fetch the __doc__ of str, because A.test already returns "Test".

我的最终目标是我的文档字符串将显示在狮身人面像中，因此除了访问属性以外，以任何其他方式检索文档字符串都是不可行的 __ doc __ 属性。我发现自己想知道这是否还有可能。

My final goal is that my docstring will appear in sphinx, so it is not feasible to retrieve the docstring in any other way than by accessing the attributes __doc__ property. I find myself wondering if this is even possible in any way.

我知道属性通过返回来解决此问题如果在没有实例的情况下调用该类。但是，很明显，这与我的目标相冲突。

I know that property solves this issue by returning the class if called without an instance. However, it should be obvious that this collides with my goal.

我开始担心在Python中这是不可能的。

I am starting to fear that this is not possible in Python.

注意：我愿意在 classproperty 中拉任何特技，只要它稳定即可（即不设置 __ doc __ 的返回值）。但是，对 classproperty 的用户施加任何负担是不可行的（即，他们只能使用装饰器并完成装饰）。

Note: I am willing to pull any stunt in classproperty as long as it is stable (i.e. not setting __doc__ on the returned value). However, it is not feasible to put any burden on the user of classproperty (i.e. they should only use the decorator and be done with it).

推荐答案

实际上， test 是一个返回字符串的属性。您必须子类 str 并赋予 __ doc __ 属性：

Indeed, test is a property returning a string. You'd have to subclass str and give that a __doc__ attribute:

class docstring_str(str):
    def __new__(cls, v, __doc__=''):
        s = super(docstring_str, cls).__new__(cls, v)
        s.__doc__ = __doc__
        return s

Demo：

>>> class docstring_str(str):
...     def __new__(cls, v, __doc__=''):
...         s = super(docstring_str, cls).__new__(cls, v)
...         s.__doc__ = __doc__
...         return s
... 
>>> s = docstring_str('Test', 'docstring')
>>> s
'Test'
>>> s.__doc__
'docstring'

用作：

class A(object):
    @classproperty
    def test(cls):
        return docstring_str("Test", "docstring')

因为 str 对象是不可变的，您不能在装饰器中设置 __ doc __ 属性，您必须返回一个代理对象，而必须完全包装实际的返回值，除了 __ doc __ 属性。这变得复杂且丑陋。

Because str objects are immutable, you cannot set the __doc__ attribute in a decorator. You'd have to return a proxy object instead that fully wraps the actual return value except for the __doc__ attribute. This gets to be complex and ugly fast.

另一种方法是将常规属性 在元类上；该类的类：

The alternative is to put a regular property on the metaclass; the class's class:

class MetaClass(type):
    @property
    def test(cls):
        "docstring"
        return "Test"

class A(object):
    __metaclass__ = MetaClass

现在 A 具有 test 属性，并且可以访问文档字符串ed为 MetaClass.test .__ doc __ 或具有 type（A）.test .__ doc __ ：

Now A has a test property, and the docstring can be accessed as MetaClass.test.__doc__ or with type(A).test.__doc__:

>>> A.test
'Test'
>>> type(A).test
<property object at 0x10757d158>
>>> type(A).test.__doc__
'docstring'

这篇关于实现保留文档字符串的类属性的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！