Docstring pour la variable

Question

Est-il possible d'utiliser docstring pour une variable simple? Par exemple, j'ai un module appelé t

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

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

et je fais

 >>> import t
>>> t.f.__doc__
'f'

mais

 >>> t.l.__doc__
>>> 

L'exemple est similaire à celui de PEP 258 (recherchez "ceci est g").

Answer 1

Epydoc autorise les docstrings sur les variables :

Bien que le langage ne les fournisse pas directement, Epydoc prend en charge chaînes de documentation variables : si une instruction d'affectation de variable est immédiatement suivi d'un littéral de chaîne nue, alors cette affectation est traitée comme une docstring pour cette variable.

Exemple:

 class A:
    x = 22
    """Docstring for class variable A.x"""

    def __init__(self, a):
        self.y = a
        """Docstring for instance variable A.y

Answer 2

Eh bien, même si Python ne traite pas les chaînes définies immédiatement après une définition globale comme une docstring pour la variable, sphinx le fait et ce n'est certainement pas une mauvaise pratique de les inclure.

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

Voici du code qui analysera un module et extraira les noms des définitions de variables globales, la valeur et une docstring qui suit.

 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

Certains scripts de documentation python ont une notation qui peut être utilisée dans la docstring module/classes pour documenter une var.

Par exemple pour spinx, vous pouvez utiliser :var et :ivar. Voir ce document (environ à mi-chemin).