Как документировать атрибуты класса в Python? [закрыто]

Я пишу облегченный класс, атрибуты которого должны быть общедоступными и лишь иногда переопределяться в определенных экземплярах. В языке Python нет условий для создания строк документации для атрибутов класса или каких-либо атрибутов, если на то пошло. Каков ожидаемый и поддерживаемый способ документирования этих атрибутов? В настоящее время я занимаюсь такими вещами:

class Albatross(object):
    """A bird with a flight speed exceeding that of an unladen swallow.

    Attributes:
    """

    flight_speed = 691
    __doc__ += """
        flight_speed (691)
          The maximum speed that such a bird can attain.
    """

    nesting_grounds = "Raymond Luxury-Yacht"
    __doc__ += """
        nesting_grounds ("Raymond Luxury-Yacht")
          The locale where these birds congregate to reproduce.
    """

    def __init__(self, **keyargs):
        """Initialize the Albatross from the keyword arguments."""
        self.__dict__.update(keyargs)

Это приведет к тому, что строка документации класса будет содержать исходный стандартный раздел строки документации, а также строки, добавленные для каждого атрибута через расширенное присвоение __doc__.

Хотя этот стиль явно не запрещен в руководстве по стилю документации , он также не упоминается как вариант. Преимущество здесь состоит в том, что он предоставляет способ документировать атрибуты вместе с их определениями, при этом создавая презентабельную строку документации класса и избегая необходимости писать комментарии, которые повторяют информацию из строки документации. Меня все еще немного раздражает то, что мне приходится писать атрибуты дважды; Я рассматриваю возможность использования строковых представлений значений в строке документации, чтобы, по крайней мере, избежать дублирования значений по умолчанию.

Является ли это вопиющим нарушением специальных соглашений сообщества? Это нормально? Есть ли способ лучше? Например, можно создать словарь, содержащий значения и строки документации для атрибутов, а затем добавить содержимое в класс __dict__и строку документации в конце объявления класса; это избавит от необходимости вводить имена и значения атрибутов дважды. edit : эта последняя идея, я думаю, на самом деле невозможна, по крайней мере, без динамического построения всего класса из данных, что кажется действительно плохой идеей, если для этого нет другой причины.

Я новичок в Python и все еще прорабатываю детали стиля кодирования, поэтому несвязанная критика также приветствуется.

Во избежание путаницы: термин « свойство» имеет в Python особое значение . Вы говорите о том, что мы называем атрибутами класса . Поскольку они всегда обрабатываются через их класс, я считаю, что имеет смысл задокументировать их в строке документации класса. Что-то вроде этого:

class Albatross(object):
    """A bird with a flight speed exceeding that of an unladen swallow.

    Attributes:
        flight_speed     The maximum speed that such a bird can attain.
        nesting_grounds  The locale where these birds congregate to reproduce.
    """
    flight_speed = 691
    nesting_grounds = "Throatwarbler Man Grove"

Я думаю, что это намного проще для глаз, чем подход в вашем примере. Если бы я действительно хотел, чтобы копии значений атрибутов отображались в строке документа, я бы поместил их рядом или под описанием каждого атрибута.

Имейте в виду, что в Python строки документации являются фактическими членами документируемых объектов, а не просто аннотациями исходного кода. Поскольку переменные атрибутов класса не являются объектами сами по себе, а являются ссылками на объекты, они не могут содержать собственные строки документов. Я думаю, вы могли бы привести аргументы в пользу строк документации по ссылкам, возможно, для описания «что должно быть здесь» вместо «что на самом деле здесь», но я считаю, что это достаточно просто сделать в строке документа содержащего класса.

Вы цитируете PEP257: Docstring Conventions, в разделе Что такое docstring указано:

Строковые литералы, встречающиеся в другом месте кода Python, также могут выступать в качестве документации. Они не распознаются компилятором байт-кода Python и недоступны в качестве атрибутов объекта времени выполнения (т.е. не назначаются __doc__), но программными средствами могут быть извлечены два типа дополнительных строк документации:

Строковые литералы, возникающие сразу после простого присваивания на верхнем уровне модуля, класса или метода __init__, называются «строками документации атрибутов».

И это объясняется более подробно в PEP 258: Строки документации атрибутов. Как объясняется выше ʇsәɹoɈ. атрибут не является объектом, которому может принадлежать __doc__, поэтому они не будут отображаться в help()pydoc. Эти строки документации можно использовать только для созданной документации.

Они используются в Sphinx с директивой autoattribute

Sphinx может использовать комментарии в строке перед назначением или специальный комментарий после назначения или строку документации после определения, которое будет автоматически документировано.

С этой целью вы можете злоупотреблять свойствами. Свойства содержат средство получения, средство установки, средство удаления и строку документации . Наивно, это было бы очень многословно:

class C:
    def __init__(self):
        self._x = None

    @property
    def x(self):
        """Docstring goes here."""
        return self._x

    @x.setter
    def x(self, value):
        self._x = value

    @x.deleter
    def x(self):
        del self._x

Тогда у вас будет строка документации, принадлежащая Cx:

In [24]: print(C.x.__doc__)
Docstring goes here.

Сделать это для многих атрибутов обременительно, но вы можете представить себе вспомогательную функцию myprop:

def myprop(x, doc):
    def getx(self):
        return getattr(self, '_' + x)

    def setx(self, val):
        setattr(self, '_' + x, val)

    def delx(self):
        delattr(self, '_' + x)

    return property(getx, setx, delx, doc)

class C:
    a = myprop("a", "Hi, I'm A!")
    b = myprop("b", "Hi, I'm B!")

In [44]: c = C()

In [46]: c.b = 42

In [47]: c.b
Out[47]: 42

In [49]: print(C.b.__doc__)
Hi, I'm B!

Затем вызов интерактивных Pythons helpдаст:

Help on class C in module __main__:

class C
 |  Data descriptors defined here:
 |  
 |  a
 |      Hi, I'm A!
 |  
 |  b
 |      Hi, I'm B!

что, я думаю, должно быть в значительной степени тем, что вам нужно.

Изменить : теперь я понимаю, что мы, возможно, вообще можем избежать необходимости передавать первый аргумент myprop, потому что внутреннее имя не имеет значения. Если последующие вызовы mypropмогут каким-то образом взаимодействовать друг с другом, он может автоматически выбрать длинное и маловероятное имя внутреннего атрибута. Я уверен, что есть способы реализовать это, но я не уверен, что они того стоят.