durusmail: qp: xml class support for .format() and .__html__()
QPY xml class support for .format()
2009-11-11
Michael Watkins (2 parts)
xml class support for .format() and .__html__()
2010-05-23
Michael Watkins (2 parts)
2010-05-24
Binger David (3 parts)
xml class support for .format() and .__html__()
Michael Watkins
2010-05-23
For your consideration before another QPY release, attached is another
patch to quoted.py replacing the prior one submitted.

In addition to providing a .format() method this patch includes a new
method  .__html__() which simply returns self. This allows QPY's xml
escape-no-more capability to be respected by other template systems and
frameworks that are supporting the __html__ method marker[1]. I've done
some testing with another templating package, Jinja2, to confirm that
change proposed behaves as expected.

As described by Mike Orr[1]:

    .__html__() is a convention used for smart escaping.  String-like
objects should return self to indicate that they're preformatted and
should not be escaped further. Other objects can define .__html__() to
indicate their preferred HTML format.  This convention is used by
literal() in webhelpers.html, and by the render functions that ship
with Pylons (render_mako, etc).  I didn't know WebOb itself also did
it.

    Previous implementations of smart escaping (Quixote, Genshi) required
preformatted objects to be a certain class.  This made it impossible
for third-party libraries to mark their objects preformatted, because
they'd have to depend on the package with the special class, which
they'd refuse to do or wouldn't know about.  Worse, they would be tied
to one specific template library rather than supporting all of them.
The .__html__ strategy allows third-party packages to define their own
string subclass with an .__html__ method rather than having to depend
on a special class in a foreign package.

A number of other projects referencing the above noted quotation or have
implemented .__html__() equivalents to what I've submitted here. [2][3][4]

PS: The original patch to provide .format() capability to xml instances
(included in the attached) has been working with no issues noted. I had a
stab at modifying the C extension but muffed that up, hence no patch for
that.

[1] http://groups.google.com/group/pylons-discuss/msg/f545900b872023e0
[2]
http://groups.google.com/group/wtforms/browse_thread/thread/cde309662816f865
[3] http://pythonpaste.org/webob/news.html#id6
[4] http://code.djangoproject.com/attachment/ticket/7261/html.diff
reply