Docstring for variable

Question

Is it posible to use docstring for plain variable? For example I have module called t

def f():
    \"\"\"f\"\"\"

l = lambda x: x
\"\"\"l\"\"\"


        

Answer 1

To add to to ford's answer about Epydoc, note that PyCharm will also use a string literal as the documentation for a variable in a class:

class Fields_Obj:
    DefaultValue=None
    """Get/set the default value of the data field"""

Answer 2

Well, even though Python does not treat strings defined immediately after a global definition as a docstring for the variable, sphinx does and it is certainly not a bad practice to include them.

debug = False
'''Set to True to turn on debugging mode. This enables opening IPython on 
exceptions.
'''

Here is some code that will scan a module and pull out names of global variable definitions, the value and a docstring that follows.

def GetVarDocs(fname):
    '''Read the module referenced in fname (often <module>.__file__) and return a
    dict with global variables, their value and the "docstring" that follows
    the definition of the variable
    '''
    import ast,os
    fname = os.path.splitext(fname)[0]+'.py' # convert .pyc to .py
    with open(fname, 'r') as f:
        fstr = f.read()
    d = {}
    key = None
    for node in ast.walk(ast.parse(fstr)):
        if isinstance(node,ast.Assign):
            key = node.targets[0].id
            d[key] = [node.value.id,'']
            continue
        elif isinstance(node,ast.Expr) and key:
            d[key][1] = node.value.s.strip()
        key = None
    return d

Answer 3

No, you can only do this for modules, (lambda and "normal") functions and classes, as far as I know. Other objects, even mutable ones inherit the docstrings of their class and raise AttributeError if you try to change that:

>>> a = {}
>>> a.__doc__ = "hello"
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
AttributeError: 'dict' object attribute '__doc__' is read-only

(Your second example is valid Python, but the string """l""" doesn't do anything. It is generated, evaluated and discarded.)

Answer 4

Properties can have docstrings! This covers the most common use case of documenting instance variables.

class A:
    def __init__(self):
        self._x = 22

    @property
    def x(self):
        "document x"
        return self._x

    @x.setter
    def x(self, value):
        self._x = value

A.x.__doc__

Answer 5

No, it is not possible and it wouldn't be useful if you could.

The docstring is always an attribute of an object (module, class or function), not tied to a specific variable.

That means if you could do:

t = 42
t.__doc__ = "something"  # this raises AttributeError: '__doc__' is read-only

you would be setting the documentation for the integer 42 not for the variable t. As soon as you rebind t you lose the docstring. Immutable objects such as numbers of strings sometimes have a single object shared between different users, so in this example you would probably actually have set the docstring for all occurences of 42 throughout your program.

print(42 .__doc__) # would print "something" if the above worked!

For mutable objects it wouldn't necessarily be harmful but would still be of limited use if you rebind the object.

If you want to document an attribute of a class then use the class's docstring to describe it.

Answer 6

A lot of answers assume you want it for offline use and points to sphinx or Epydoc.

But if you want it for runtime use the answer is that is impossible to add an attribute to another attribute. So you can't attach a doctring to variable.

When you do:

a = True
print(a.__doc__)

You'll be getting the docstring for the bool class. In my application I need it for plug-ins. What I do is to use an associated variable/attribute.

Something like this:

a = True
_help_a = "help for a variable"

As this looks ugly what I'm actually using are syntactic macros (take a look a macropy module). The code looks like this:

with document:
    a = True
    """ help for a variable """

I explain the whole idea here