You have a chunk of arbitrary data taken from user input, from a file, or from a database. You wish to include it in the HTML output generated by a Quixote handler. This means that '<', '>', and '&' characters in the data need to be turned into the HTML entities '<', '>', and '&'.
You can do the escaping manually, putting in calls to cgi.escape() as needed:
from quixote import get_field import cgi ... def page(): paragraph = get_field('para') or 'No text provided' return '<p>%s</p>' % cgi.escape(paragraph)
Or, you can use the htmlescape() function to get an instance of the htmltext type; this type will take care of escaping data when it's combined with strings:
from quixote import get_field from quixote.html import htmlescape, htmltext def page(): paragraph = get_field('para') or 'No text provided' return htmltext('<p>') + htmlescape(paragraph) + htmltext('</p>')
A second problem is the opposite error, quoting too many times so that users end up seeing <p>&... on your pages. In a complicated application you'll have utility functions to format a specific type of object, or generate some frequently-used text. Should these utility functions return already-escaped data, or should it be the caller's responsibility? It's easy to get it wrong and run the data through html_quote() twice. This error is just embarrassing, but doesn't open any security holes like forgetting to escape does.
The htmltext type simplifies the problem; if it's an htmltext instance, it's already been quoted and is safe to output. htmlescape() is a counterpart of cgi.escape() that returns htmltext instead of a regular Python string, so data can be passed through htmlescape() any number of times but will only be escaped once.
If you decide to use the htmltext constructor, be sure to use it only with string literals, or with data you're very sure is safe, because passing a string to the constructor says that the string is safe to output.
You can either create htmltext instances manually, or you can use the HTML template type in PTL, which turns the second example above into the following PTL code:
def page [html] (): paragraph = get_field('para') or 'No text provided' '<p>' paragraph '</p>'
In an HTML template, string literals in the code are automatically turned into htmltext instances. Properly written HTML templates will never need to use the htmltext() constructor explicitly.
Consult the doc/PTL file in the Quixote source distribution for more details about PTL and the htmltext type.