What is the difference between var, cvar and ivar in python sphinx?

Question

I read the pages of the sphinx documentation and ironically discovered that the documentation on the difference between var, ivar and cvar is very lacking. I was wondering if anyone could explain the difference between each of the different namespaces in the inline code.

Example:

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

How each of these sphinx tags is different from each other and how can I find out which one is correct in order to use it correctly, how was it developed?

Answer 1

var is a shared variable, of course. Use this when you do not want to make any further differences to the variable you are documenting.

ivar is an "instance variable" or a variable defined for an instance of an object (an instance of a class). Usually they will be defined (in Python) inside the __init__ method.

cvar is a "class variable" or a variable that is directly set to a class object. Typically, this would be set inside the class operator, but outside of any particular method in the class.

Here is an example:

 class SomeClass(object): cvar = 'I am a class variable' def __init__(self): self.ivar = 'I am an instance variable' 

Answer 2

Maybe you should not worry about the difference between thesr-specific tags and just stick with "var" if you need to use it at all, as the documentation indicates that:

There are many other Info fields, but they can be redundant: ... (including) ... var, ivar, cvar: Description of the variable. ...

Cm:

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