документация собственности - PullRequest
Новая
       18

документация собственности

2 голосов
/ 15 февраля 2012

Рассмотрим код: 

class MyClass(object):
  '''
  Keep track of file and its path on disk
  '''

  def __init__(self):
    self.file = None
    self.path = None

Я хотел бы добавить строку документации ко всем свойствам.Итак, я мог бы сделать что-то вроде (для свойства файла): 

class MyClass(object):
  ...

  @property
  def file(self):
    '''
    this is a doc-string for file property
    '''

    return self._file

  @file.setter
  def file(self, value):
    self._file = value

  @file.deleter
  def file(self):
    del self._file

Однако для каждого свойства утомительно писать методы получения, установки и удаления.На самом деле эти методы (как видно выше) выполняют задание по умолчанию.

Есть ли простой способ добавить строку свойств в свойства?

Ответы [ 5 ]

2 голосов
/ 15 февраля 2012

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

class DocProperty(object):

    def __init__(self, doc=None):
        self._values = {}
        self.__doc__ = doc

    def __get__(self, obj, objtype=None):
        if obj is None:
            return self
        return self._values[obj]

    def __set__(self, obj, value):
        self._values[obj] = value

    def __delete__(self, obj):
        del self._values[obj]

Затем вы можете использовать его следующим образом: 

class SomeClass(object):

    p1 = DocProperty('some docs')

print SomeClass.p1.__doc__
# some docs
c = SomeClass()
c.p1 = 2
print c.p1
# 2
del c.p1

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

1 голос
/ 15 февраля 2012

Это исправленная версия класса DocProperty DzinX: 

class DocProperty(object):

    def __init__(self, name, doc):
        self._name = '_'+name
        self.__doc__ = doc

    def __get__(self, obj, objtype=None):
        if obj is None:
            return self
        return getattr(obj, self._name)

    def __set__(self, obj, value):
        setattr(obj, self._name, value)

    def __delete__(self, obj):
        delattr(obj, self._name)

Использование: 

class SomeClass(object):
    p1 = DocProperty('p1', 'some docs')

Обратите внимание, что использование этого сделает ваш код менее эффективным - каждый доступ к атрибутам становится дороже. Но я предполагаю, что в некоторых контекстах возможность добавления документов может стоить того (особенно если эффективность не имеет значения в вашем контексте).

0 голосов
/ 05 мая 2017

Вы имели в виду атрибуты (определенные в init в начале вопроса) или свойства, как указано?

Для свойств просто поместите строку документа в метод получения.Вы можете получить к нему доступ как my_class_instance.__class__.file.__doc__.

Использование такой IDE, как PyCharm, может помочь вам создать свойства.В PyCharm вы просто начинаете вводить «prop», и всплывающее окно поможет вам создать полный шаблон для свойств только для чтения, чтения / записи и т. Д.

0 голосов
/ 15 февраля 2012

Если вы генерируете документы API с помощью инструмента, подобного epydoc (который генерирует веб-страницу, описывающую API вашего кода), то вы можете использовать переменную строку документации .Но если вы хотите, чтобы строки документов были доступны для интерактивного / рефлексивного использования, то ответ DzinX, вероятно, поможет вам.

0 голосов
/ 15 февраля 2012

Не уверен, что вы ищете это, но если вы используете Sphinx для своей системы документации, вы можете поместить свойство doc с этим синтаксисом: 

class MyClass(object):
  '''
  Keep track of file and its path on disk
  '''

  def __init__(self):
    #: this is doc for file
    self.file = None

    #: this is the documentation for path
    #: on multiple line too.
    self.path = None
...