Документирование атрибута класса

Question

Следующий пример взят из книги «Погружение в питона».

class MP3FileInfo(FileInfo):
    "store ID3v1.0 MP3 tags"
    tagDataMap = ...

В этом примере показано документирование MP3FileInfo, но как я могу добавить справку в MP3FileInfo. tagDataMap

Answer 1

PEP 224 для строк документации атрибутов было отклонено (давно), так что это проблема и для меня, иногда я не знаю, выбрать ли атрибут класса или свойство экземпляра - второй может иметь строку документации.

Answer 2

Измените его на метод свойства.

Answer 3

Сделай так:

class MP3FileInfo(FileInfo):
    """Store ID3v1.0 MP3 tags."""

    @property 
    def tagDataMap(self):
        """This function computes map of tags.

        The amount of work necessary to compute is quite large, therefore
        we memoize the result.

        """
        ...

Обратите внимание, что вам не следует создавать отдельную строку документации, если атрибут имеет только однострочное описание. Вместо этого используйте

class MP3FileInfo(FileInfo):
    """Store ID3v1.0 MP3 tags.

    Here are the attributes:
        tagDataMap -- contains a map of tags

    """

    tagDataMap = ...