В чем разница между var, cvar и ivar в sphinx python?

Question

Я читал страницы документации по сфинксу и иронически обнаружил, что документации по разнице между var, ivar и cvar очень не хватает. Мне было интересно, может ли кто-нибудь объяснить разницу между каждым из разных пространств имен в встроенном коде.

Пример:

class foo(object): 
    """ 
     :var str first: 
     :ivar str last: 
     :cvar str middle: 
    """ 

Как каждый из этих сфинксов теги отличаются друг от друга, и, как я знаю, какой из них является правильным, чтобы правильно использовать как задумано?

Answer 1

Может быть, не беспокоиться о различии между thesr определенными тегами и просто придерживаться использования «вар», если вам нужно использовать его на всех, поскольку документация указывает на то, что:

Есть много других полей Info, но они могут быть избыточными: ... (включая) ... var, ivar, cvar: Описание переменной. ...

См:

http://thomas-cokelaer.info/tutorials/sphinx/docstring_python.html

Answer 2

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

ivar является «переменной экземпляра» или переменной, заданной для экземпляра объекта (экземпляра класса). Обычно они будут определены (в Python) внутри метода __init__.

cvar - это «переменная класса» или переменная, которая непосредственно устанавливается на объект класса. Как правило, это должно быть установлено внутри оператора класса, но вне любого конкретного метода в классе.

Вот пример:

class SomeClass(object): 

    cvar = 'I am a class variable' 

    def __init__(self): 
     self.ivar = 'I am an instance variable'