contenu dans docstrings Répétitif

Question

Quelles sont les bonnes façons de traiter le contenu répétitif docstrings? J'ai beaucoup de fonctions qui prennent des arguments « standard », qui doivent être expliqué dans le docstring, mais ce serait bien d'écrire les parties pertinentes du docstring qu'une seule fois, car cela serait beaucoup plus facile à maintenir et mettre à jour. J'ai essayé naïvement ce qui suit:

arg_a = "a: a very common argument"

def test(a):
    '''
    Arguments:
    %s
    ''' % arg_a
    pass

Mais cela ne fonctionne pas, parce que quand je fais help(test) je ne vois pas le docstring. Y at-il une bonne façon de le faire?

Answer 1

Comme les autres réponses disent, vous devez changer l'élément __doc__ de l'objet de la fonction. Une bonne façon de le faire est d'utiliser un décorateur qui effectuera la mise en forme sur le docstring:

def fixdocstring(func):
    func.__doc__ = func.__doc__.replace('<arg_a>', 'a: a very common argument')
    #(This is just an example, other string formatting methods can be used as well.)
    return func

@fixdocstring
def test(a):
    '''
    Arguments:
    <arg_a>
    ''''
    pass

Answer 2

__doc__ est assignable sur la plupart des types définis par l'utilisateur:

arg_a = "a: a very common argument"

def test(a):
    pass

test.__doc__ = '''
    Arguments:
    %s
    ''' % arg_a

Answer 3

Il n'y a pas de façon évidente de le faire autant que je sache (du moins pas sans réaffectant __doc__ comme explicitement Ignacio suggère).

Mais je pense que ce serait une chose terrible à faire. Considérez ceci:

Que faire si je navigue dans votre code et la lecture de ce docstring sur la ligne 300-e de votre dossier? Tu veux vraiment que je vais recherche pour l'argument?