在文档字符串中存储HTML模板？

Question

我正在用Flask写一个内部应用的网络服务。在这个服务中，很多网址会返回一些HTML片段。我想找个简单的方法来存储这些HTML模板字符串。我不想把模板字符串放在单独的文件里，因为它们通常只有几行，而且我不想有20个文件，每个文件里只有3行内容。我在考虑把函数的HTML模板字符串放在函数的文档字符串里，这样可以有多个好处。它不仅可以作为文档，基本上就是在说“这就是我输出的内容”，还可以让我不必把3行的模板字符串放在不同的文件里。下面是我说的内容：

@app.route('/path/to/my/resource/<int:_id>')
def some_resource(_id):
    """
    <select id="resource-{{ resource.id }}" class="resource">
        {% for choice in choices %}
        <option id="choice-{{ choice.id }}" value="{{ choice.id }}">
            {{ choice.text }}
        </option>
        {% endfor %}
    </select>
    """

    # retrieving resource, etc...

    return render_template_string(some_resource.__doc__, **kwargs)

我不知道这样做是否会让维护变得很麻烦……你们有什么想法吗？

Answer 1

在一些模板引擎中，如果一个对象有一个__html__的方法，那么它的输出会被当作一个安全的（经过处理的）字符串来对待。

def fn(x):
    bla = x
fn.__html__ = lambda : '''
    <h1>Headline</h1>
    <p>lorem ipsum</p>
    '''

Answer 2

这个想法确实很有趣，像 doctest 这样的例子也表明，把有用的功能放在文档字符串里，而不仅仅是文字描述，这并不是完全不可能。不过，明显的缺点是，这样的话文档字符串里就没有说明文档了。如果这些方法并不是程序员需要通过 help()（或者通过自动生成的文档）来查阅的内容，这可能不是个大问题。

不过，为什么不考虑以下几种方法呢：

1. 直接使用一个局部字符串变量 - 缺点是你无法从函数外部通过 __doc__ 来访问它。
2. 如果只用一次，就直接放在 render_template_string 调用里 - 这和第一种方法有相同的缺点，但如果用的不止一次就不适用了。
3. 创建一个新的装饰器，把这个字符串作为参数传入 - 特别是当你只用一次，并且最后总是调用同样的内容时，这样可以让你把它从那个方法中提取出来。

Answer 3

我觉得这个计划不好。

文档字符串是用来写说明的，而模板并不是说明。说明应该告诉我们这个函数是用来干什么的。用HTML模板来代替说明是个很糟糕的选择。

你可以用多行字符串来保存你的模板，这样做可能更好。把它们当作文档字符串没有什么好处。