store html templates in docstrings?

Question

I am using Flask to write a web service for an internal app here at my work. Many of the web services URI’s return HTML partials, and I am trying to figure out a clean way to store the html template strings. I don’t want to put the template strings in separate files, since they are usually only a few lines long and I don’t want to have 20 template files that each have 3 lines in them. I was thinking about defining a function’s html template string in the docstring of the function, as I feel like that would serve multiple purposes. It would serve as documentation, basically saying “this is what I output”, as well as keeping me from having to store 3-line templates strings in separate files. Here is what I am talking about:

@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)

I don’t know whether this would be a nightmare to maintain or not…any thoughts?

Asked By: user35288

||

Source

Answer 1

I think its a bad plan.

Docstrings are for documentation, the template is not documentation. Documentation is supposed to describe what the function is being used for. An HTML template is a poor substitute for that.

You can use multi-line strings to hold your template, and thats probably a good idea. You don’t gain anything by making them docstrings.

Answered By: Winston Ewert

Answer 2

It’s certainly an interesting idea, and following the example of doctest, it’s not entirely unheard of to put functionally-useful things in your docstrings instead of just text. The obvious drawback is that then there’s no documentation in the docstring. Now, this may or may not be a huge problem if the methods are not something that programmers will likely need documentation on via help() (or by auto-generated docs using the docstrings).

However, why not either:

just use a local string variable – the downside would be that you can’t get at it via __doc__ from outside the scope of the function
if it’s just used that once, just put it into the render_template_string call – same drawbacks as #1, but also doesn’t apply if it’s used more than once
create another decorator that takes this string as an argument – especially if it just follows the pattern above where you’re just using it the once and you’re always doing the same call at the end, this would allow you to pull it out of that method

Answered By: Daniel DiPaolo

Answer 3

In some templating engines, if an object has a __html__ method, it’s output is treated as a safe (escaped) string.

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

Answered By: XORcist

store html templates in docstrings?

Question:

Answers: