用于do_help（）函数的Python cmd动态文档字符串

Question

我正在使用Pythonic命令行“flashcard”应用程序来帮助用户学习不同的语言。我想使用Python的cmd库来加速开发 - 特别感兴趣的是cmd.Cmd类的do_help（）方法，它打印了类的用户方法的doc字符串。但是，由于此应用程序的多语言特性，我希望能够使用特定于语言的文档字符串。

我读过关于使用装饰器的this SO question，但我对装饰器知之甚少，而且我想知道在投入大量时间学习它们之前它们是否适合我的特定困境。

你们觉得怎么样？处理这种情况的最佳方法是什么？

如果您想了解有关我的问题的更多信息，请与我们联系。

Answer 1

装饰者将能够做你想做的事情以及更多。

装饰底漆

作为额外的奖励，装饰器在各种情况下都是非常有用的工具。他们真的不那么可怕。在Essence中，它们是将函数作为参数并返回函数的函数。一个非常简单的示例打印出呼出结果：

>>> 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!'

将args传递给装饰器

如果你必须为每个函数创建一个装饰器，这是非常繁重的。您可以使用文档字典轻松开发通用解决方案：

>>> 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代码中使用它。

自动文档字符串转换策略

您可以通过检查模块的docstrings以编程方式生成文档字典。

来自评论：

  

这个想法是字典是从你的文档字符串自动生成的，然后传递给翻译者。如果您更改了规范（英语？）docstring，那么翻译也必须更改。通过将旧的转换表与新生成的表进行比较，您可以重新插入规范文档字符串未更改的转换。您只需要为新文档字符串添加翻译。

因此，例如，在将foo()文档字符串更改为"""goodbye, doc..."""之后，您将重新运行表生成器，并且您将获得一个新表，其中缺少旧的“hello doc”键，您的翻译表中有一个新的键值对("goodbye, doc...", "")。

替代使用cmd模块的help_<cmd>()样式

如果您更倾向于使用help_<cmd>()模块的{{1}}样式作为文档，您可以使用相同的原则将您的翻译存储在字典中，并根据以下内容打印出正确的翻译。帮助命令中的LANG变量。