Как я могу сделать атрибуты объекта документа Python / Sphinx, объявленные только в __init__?

Question

У меня есть классы Python с атрибутами объекта, которые объявлены только как часть запуска конструктора, например:

class Foo(object):
    def __init__(self, base):
        self.basepath = base

        temp = []
        for run in os.listdir(self.basepath):
            if self.foo(run):
                temp.append(run)
        self.availableruns = tuple(sorted(temp))

Если я сейчас использую help(Foo) или попытка документировать Foo в Сфинксе, self.basepath а также self.availableruns Атрибуты не отображаются. Это проблема для пользователей нашего API.

Я пробовал поиск стандартного способа, чтобы убедиться, что эти «динамически объявленные» атрибуты могут быть найдены (и предпочтительно DOCSTRING'D) по парсеру, но не повезло. Какие-либо предложения? Спасибо.

Answer 1

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

class Foo(object):
     #: Doc comment for availableruns
     availableruns = ()

    def __init__(self, base):
        ...
        self.availableruns = tuple(sorted(temp))

Действительно, если переменная экземпляра имеет полезную неизменный Значение по умолчанию (например, none или пустой кортеж), то вы можете сохранить небольшую память, просто не устанавливая переменную, если должно иметь значение по умолчанию. Конечно, этот подход не будет работать, если вы говорите о переменной экземпляра, которую вы можете удалить (например, del foo.availableruns) - Но я нахожу это не очень распространенное дело.

Если вы используете SPHINX, и имеете установку «Auttribute», то это должно быть задокументировано соответствующим образом. Или, в зависимости от контекста того, что вы делаете, вы могли бы просто напрямую использовать SPHINX .. py:attribute:: Директива.

Answer 2

Я пробовал поиск стандартного способа, чтобы убедиться, что эти «динамически объявленные» атрибуты могут быть найдены (и предпочтительно DOCSTRING'D) по парсеру, но не повезло. Какие-либо предложения?

Они не могут быть «обнаружены» любым парсером.

Python имеет setattr. Отказ Полный набор атрибутов никогда не «обнаруживается», в любом смысле этого слова.

Вы абсолютно должны описать их в DocString.

Если вы не хотите сделать кучу мета-программирования, чтобы сгенерировать DocStrings из того, что вы собрались inspect или что-то. Даже тогда ваше «решение» будет неполным, как только вы начинаете использовать setattr.]

class Foo(object):
    """
    :ivar basepath:
    :ivar availableruns:
    """
    def __init__(self, base):