хранить шаблоны HTML в docstrings? - PullRequest
Новая
       10

хранить шаблоны HTML в docstrings?

1 голос
/ 12 марта 2011

Я использую Flask, чтобы написать веб-сервис для внутреннего приложения здесь, на моей работе.Многие из URI веб-служб возвращают 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)

Я не знаю, будет ли это кошмаром поддерживать или нет ... какие-то мысли?

Ответы [ 3 ]

4 голосов
/ 12 марта 2011

Я думаю, что это плохой план.

Строки документации предназначены для документации, шаблон не является документацией. Документация должна описывать, для чего используется функция. Шаблон HTML - плохая замена этому.

Вы можете использовать многострочные строки для хранения вашего шаблона, и это, вероятно, хорошая идея. Ты ничего не получишь, сделав из них строки документации.

0 голосов
/ 12 марта 2011

В некоторых шаблонизаторах, если у объекта есть метод __ html __ , его вывод обрабатывается как безопасная (экранированная) строка. 

def fn(x):
    bla = x
fn.__html__ = lambda : '''
    <h1>Headline</h1>
    <p>lorem ipsum</p>
    '''
0 голосов
/ 12 марта 2011

Это, безусловно, интересная идея, и, следуя примеру doctest, вполне возможно, что в ваши строки документации будут вставлены функционально полезные вещи, а не просто текст.Очевидным недостатком является то, что в документации нет документации.Теперь, это может или не может быть огромной проблемой, если методы не являются чем-то, что программистам, вероятно, потребуется документация через help() (или автоматически сгенерированными документами с использованием строк документации).

Однако почему бы и нетлибо:

  1. просто используйте локальную строковую переменную - недостатком будет то, что вы не можете получить ее через __doc__ вне области действия функции
  2. если он используется один раз, просто поместите его в вызов render_template_string - те же недостатки, что и # 1, но он также не применяется, если он используется более одного раза
  3. создать другой декоратор, который принимает эту строку в качестве аргумента - особенно если он просто следует приведенному выше шаблону, где вы просто используете его один раз, и вы всегда делаете один и тот же вызов в конце, это позволитвы вытащить его из этого метода
...