Question

根据PEP 257命令行脚本的docstring应该是它的用法消息：

脚本（独立程序）的docstring应该可用作其“用法”消息，当使用不正确或缺少的参数调用脚本时打印（或者使用“-h”选项，求助”）。这样的docstring应记录脚本的功能和命令行语法，环境变量和文件。用法消息可以相当复杂（几个屏幕已满），并且应该足以让新用户正确使用该命令，以及对复杂用户的所有选项和参数的完整快速参考。

docstring应该是第一个作为模块级别的字符串，在其他任何东西之前，可以作为__doc__使用。

现在，我还使用docopt作为用法消息解析器，所以我只需要编写doc字符串，并且它自己构建命令行解析器，这很好。

_("""...""")

什么不是那么好，是我找不到将文档字符串标记为get18的i18nable的方法，所以我可以在给docopt时将其转换为其他语言。当时我得到的唯一解决方案是在翻译所有应用程序的其他字符串时使用和帮助消息保持英文！

正如PEP 20所述：

应该有一个 - 最好只有一个 - 显而易见的方法虽然这种方式起初可能并不明显，除非你是荷兰人。

什么是解决无法将文档字符串标记为可翻译优雅的限制的最佳方法？

注意：在这里，我们认为我在gettext.install()模块中执行__init__.py，以便在解析偶数_()之前内置函数中存在__doc__。

Answer 1

目前，这是我想要的解决方案：

"""\
This is the docstring
"""

import docopt
if __name__ == "__main__":
    try:
        args = docopt.docopt(_("{docstring}").format(docstring=__doc__))
    except KeyError:
        args = docopt.docopt(_("{docstring}")) # string which will be replaced by the i18ned one.

我没有找到那么优雅，因为即使python中的例外是可以的，我认为它们应该被保留为例外而不是应用程序的用例。

它也是一个非常顽皮的黑客，它会在gettext中获取docstring格式，而不是__docopt__文本，这将无法帮助翻译，因为他们将不得不回到源代码......

Answer 2

我终于找到解析文档字符串的唯一好方法：

-D
--docstrings
    Extract module, class, method, and function docstrings.  These do
    not need to be wrapped in _() markers, and in fact cannot be for
    Python to consider them docstrings. (See also the -X option).

将提取所有文档字符串。因此，唯一需要翻译的内容可以使用以下内容进行翻译：

args = docopt.docopt(_(__doc__))

Answer 3

另一种方式：

if __name__ == "__main__":
    if hasattr(vars()['__builtins__'], '_') and not 'NullTranslations' in str(_):
        args = docopt.docopt(_("USAGE MESSAGE"))
    else:
        args = docopt.docopt(__doc__)

没有使用异常，但是使用方法的字符串表示法进行输入测试，并在内置模块中查找该方法...这并不比其他选项更好。

那个也是一个非常糟糕和不优雅的黑客，因为翻译人员必须参考源代码来查找文档字符串。或者我必须在代码中有两次docstring的内容。

如何让docstring尊重PEP257，同时可以使用docopt来使用gettext来符合i18n？

3 个答案: