Декораторы смогут делать то, что вы хотите, и даже больше.
Декоратор грунтовки
В качестве дополнительного бонуса декораторы являются очень полезными инструментами в самых разных ситуациях. Они действительно не такие страшные. В сущности, это функции, которые принимают функцию в качестве аргумента и возвращают функцию. Очень простой пример печатает результат вызова:
>>> def my_decorator(function):
... def inner_function(*args, **kwargs):
... res = function(*args, **kwargs)
... print("We have: "+res)
... return res
...
>>> @my_decorator
... def add(x, y):
... return x+y
...
>>> add(1,2)
We have: 3
3
Это эквивалентно
add = my_decorator(add)
Для вашей проблемы декоратор просто должен переопределить свойство __doc__ функции.
>>> def frenchmeup(fun):
... fun.__doc__ = "Bonjour, documentation!"
... return fun
...
>>> @frenchmeup
... def foo():
... """hello doc"""
... return "world"
...
>>> foo.__doc__
'Bonjour, documentation!'
Передача аргументов в декораторы
Это довольно обременительно, если вам нужно создать декоратор для каждой функции. Вы можете легко разработать общее решение, используя словарь документации:
>>> ttable = {
... "FR" : {
... "hello doc": "Bonjour, documentation!"
... }
... }
>>> def document(lang=None):
... def doc_decorator(function):
... if lang and lang in ttable:
... function.__doc__ = ttable[lang][function.__doc__]
... return function
... return doc_decorator
...
>>> @document(lang="FR")
... def foo():
... """hello doc"""
... return 42
...
>>> foo.__doc__
'Bonjour, documentation!'
Не так, как декоратор теперь генерируется функцией. Это более сложно, но дает вам возможность передавать аргументы в декоратор.
Как личное замечание, прошло некоторое время, прежде чем это щелкнуло для меня, но теперь я регулярно использую его в своем коде Python.
Стратегия автоматического перевода документации
Вы можете фактически сгенерировать словарь документации программно, проверив ваш модуль на наличие строк документации.
Из комментариев:
Идея состоит в том, что словарь автоматически генерируется из ваших строк документации и затем передается переводчику. Если вы изменили каноническую (английскую?) Строку документации, то переводы также должны быть изменены. Сравнивая старую таблицу перевода с новой сгенерированной таблицей, вы сможете повторно вставить переводы, для которых каноническая строка документации не изменилась. Вам нужно только добавить перевод для новой строки документации.
Так, например, после изменения строки документа foo() на """goodbye, doc...""" вы перезапустите генератор таблиц и получите новую таблицу с отсутствующим старым ключом "hello doc" и новым ключом. -значение пары ("goodbye, doc...", "") в вашей таблице перевода.
Альтернатива с использованием стиля help_<cmd>() для модуля cmd
Если вы предпочитаете использовать стиль help_<cmd>() модуля cmd для документации, вы можете использовать тот же принцип хранения переводов в словаре и распечатки правильного перевода на основе Переменная LANG в команде справки.