Conteúdo repetitivo em Docstrings

Question

Quais são as boas maneiras de lidar com conteúdo repetitivo no DocStrings? Eu tenho muitas funções que assumem argumentos 'padrão', que precisam ser explicados no Docstring, mas seria bom escrever as partes relevantes do Docstring apenas uma vez, pois isso seria muito mais fácil de manter e atualizar. Eu tentei ingenuamente o seguinte:

arg_a = "a: a very common argument"

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

Mas isso não funciona, porque quando eu faço help(test) Eu não vejo o docstring. Existe uma boa maneira de fazer isso?

Answer 1

Como dizem as outras respostas, você precisa mudar o __doc__ membro do objeto de função. Uma boa maneira de fazer isso é usar um decorador que realizará a formatação no documental:

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

teria pensado que "classes de implementação de valor" como uma chave de extensão tome mais sentido do que o que você tem lá (caso contrário, como é saber que você está falando sobre os valores do mapa e não as chaves?)

Answer 3

Não há uma maneira óbvia de fazer isso até onde eu sei (pelo menos não sem explicitamente transferindo __doc__ como sugere Ignacio).

Mas acho que isso seria uma coisa terrível de se fazer. Considere isto:

E se eu estiver navegando pelo seu código e lendo esse documento na linha de 300º do seu arquivo? Você realmente quer que eu vá procurar para o argumento?