使用文档字符串记录 Python @property“属性”[重复]

Question

我认为文档字符串更多的是个人喜好，但我想得到一些比我聪明的人的意见......

这是记录 get/set 性质 pythons @property 描述符属性的合法方式吗？

class Handle(rgm.RigModule):
    '''
    Handle nodes are intended to be keyable transforms, made viewable by shape nodes connected as children

    @Properties:

        parent:
            Transform: Returns Transform instance if parent exists, otherwise None
        parent.setter:
            (str): Sets parent transform. (Accepts string name of transform, or any instance of the Transform class)

        shape:
            str: returns string representation of current shape
        shape.setter:
            (str): sets current shape using string representation provided.  If string key does not exist in library, shape will be set to None

        shapeDraw:
            dict: returns dictionary of shape data
        shapeDraw.setter:
            (dict): sets current shapes using data

        shapeColor:
            int: returns integer representation of current shape color
        shapeColor.setter:
            (int): sets current shape color using integer provided.

        shapeColor:
            int: returns integer representation of current shape color
        shapeColor.setter:
            (int): sets current shape color using integer provided.

        shapeTranslate:
            list: returns a 3list of the shape nodes relative offset translation
        shapeTranslate.setter:
            (list): sets relative offset translation of the shape nodes

        shapeRotate:
            list: returns a 3list of the shape nodes relative offset rotation
        shapeRotate.setter:
            (list): sets relative offset rotation of the shape nodes

        shapeScale:
            list: returns a 3list of the shape nodes relative offset scale
        shapeScale.setter:
            (list): sets relative offset scale of the shape nodes

        shapeMatrix:
            list: returns a 8list of the shape nodes relative offset matrix
        shapeMatrix.setter:
            (list): sets relative offset matrix of the shape nodes

Answer 1

Docstring 格式取决于您使用的 IDE 或自动文档生成工具。我可以举一个 PyCharm IDE 的例子，因为我一直在工作中使用它。

如果您使用 PyCharm，则文档字符串是增强 IDE 分析器结果的强大方法。您可以阅读很多关于如何为此 IDE here 编写“正确”文档字符串的信息。下面是一些例子：

class Character(object):
    pass


class Item(object):

    def __init__(self, owner=None):
        """
        :type owner: Character or None
        """
        self.__owner = owner

    @property
    def owner(self):
        """:rtype: Animal"""
        return self.__owner

    @owner.setter
    def owner(self, value):
        """:type value: Character"""
        self.__owner = value


class ArmorItem(Item):
    def __init__(self, defence, owner=None):
        """
        :type defence: int
        :type owner: Character or None
        """
        super(ArmorItem, self).__init__(owner)
        self.__defence = defence

    @property
    def defence(self):
        """:rtype: int"""
        return self.__defence


class Shield(ArmorItem):

    def block(self, damage):
        """
        :param int damage: The damage that can hero get
        :rtype: bool
        """
        if self.defence > damage:
            return True
        return False


class Helm(ArmorItem):

    def save(self, damage):
        """
        :param int damage: The damage that can hero get
        :rtype: bool
        """
        if self.defence > damage:
            return True
        return False


class Sword(Item):

    def __init__(self, damage, owner=None):
        """
        :type damage: int
        :type owner: Character or None
        """
        super(Sword, self).__init__(owner)
        self.__damage = damage


class Hero(Character):

    def __init__(self, name, weapon, armors):
        """
        :param str name: Hero name
        :param weapon weapon: Hero weapon
        :param list of ArmorItem armors: The armor item that have hero
        """
        super(Hero, self).__init__()

        self.__name = name
        self.__weapon = weapon

        self.__armors = armors
        for armor in self.__armors:
            armor.owner = self

    @property
    def name(self):
        """:rtype: str"""
        return self.__name

    @property
    def weapon(self):
        """:rtype: Sword"""
        return self.__weapon

    @property
    def armors(self):
        """:rtype: list of ArmorItem"""
        return self.__armors


def main():
    """
    Here method documentation can be placed.
    There is a test function to show analyzer facilities when a good docstring specified.

    Of course where I wrote "error" it mean that not Python exception will be thrown.
    In this place analyzer (e.g. PyCharm) show that it's something wrong.
    """
    weapon_bad1 = Sword(34.2)  # Error because damage is not int
    weapon_bad2 = Sword(20, weapon_bad1)  # Error because owner is not appropriate class

    weapon = Sword(10)  # Ok
    helm = Helm(20)  # Ok
    shield = Shield(30)  # Ok

    # Specify that all_items it not list but it list of Item (any)
    all_items = [weapon, helm, shield]
    """:type: list of Item"""

    hero_bad = Hero("bad", weapon, all_items)  # Again error here because all_items is not ArmorItem list
    hero_good = Hero("good", weapon, [helm, shield])

    # "Cast type" to notify analyzer that we get not ArmorItem but we get concrete ArmorItem
    some_armor = hero_good.armors[0]
    """:type: Helm"""

    some_armor.save(10)  # Ok, Helm class has save method
    some_armor.block(10)  # Error, Helm class has not block method


if __name__ == "__main__":
    main()

如果在每个方法中指定正确的文档字符串，您可以在 IDE 中看到什么：

注意 PyCharm IDE 分析器可以在指定文档字符串时提供很大帮助（您可以在答案开头的链接中找到文档字符串格式的扩展列表）。