Повторяющийся контент в строках документов

Question

Каковы хорошие способы борьбы с повторяющимся содержимым в строках документов? У меня есть много функций, которые принимают «стандартные» аргументы, которые должны быть объяснены в строке документации, но было бы неплохо написать соответствующие части строки документа только один раз, поскольку это было бы намного проще поддерживать и обновлять. Я наивно пробовал следующее:

arg_a = "a: a very common argument"

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

Но это не работает, потому что когда я делаю help(test), я не вижу строку документации. Есть ли хороший способ сделать это?

Answer 1

Как говорят другие ответы, вам необходимо изменить __doc__ член функционального объекта. Хороший способ сделать это - использовать декоратор, который будет выполнять форматирование строки документации:

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__ присваивается большинству пользовательских типов:

arg_a = "a: a very common argument"

def test(a):
    pass

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

Answer 3

Насколько мне известно, не существует очевидного способа сделать это (по крайней мере, без явного переназначения __doc__, как предлагает Игнасио).

Но я думаю, это было бы ужасно. Учтите это:

Что если я перемещаюсь по вашему коду и читаю эту строку документации в 300-й строке вашего файла? Вы действительно хотите, чтобы я пошел искать аргумент?