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

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

8 голосов
/ 18 октября 2010

У меня есть классы 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 в Sphinx, атрибуты self.basepath и self.availableruns не отображаются. Это проблема для пользователей нашего API.

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

Ответы [ 2 ]

8 голосов
/ 18 октября 2010

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

Они не могут быть "обнаружены" никаким парсером.

Python имеет setattr. Полный набор атрибутов никогда не может быть обнаружен в любом смысле этого слова.

Вы обязательно должны описать их в строке документации.

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

class Foo(object):
    """
    :ivar basepath:
    :ivar availableruns:
    """
    def __init__(self, base):
2 голосов
/ 18 июля 2011

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

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

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

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

Есливы используете sphinx, и у вас установлен "autoattribute", тогда это должно быть соответствующим образом задокументировано.Или, в зависимости от контекста того, что вы делаете, вы можете просто напрямую использовать директиву Sphinx .. py:attribute::.

...