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

Question

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

arg_a = "a: a very common argument"

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

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

Answer 1

Как говорят другие ответы, вам нужно изменить __doc__ Член функционального объекта. Хороший способ сделать это - использовать декоратор, который выполнит форматирование на 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__ назначается на большинство пользовательских типов:

arg_a = "a: a very common argument"

def test(a):
    pass

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

Answer 3

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

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

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