[Web-SIG] A trivial template API counter-proposal

[Phillip J. Eby]

At 08:17 AM 2/4/2006 -0800, Guido van Rossum wrote:
>[Phillip]
> > API to be provided by a "template engine":
> >
> > compile_string(text), compile_stream(input_stream) - return a WSGI
> > application object for the template described by the text or file-like 
> object
> >
> > write_compiled(app, output_stream) - save the compiled form of the template
> > to output_stream
> >
> > read_compiled(input_stream) - read a template from input_stream and return
> > a WSGI application object
>
>I am probably missing something, but shouldn't there also be an API to
>render the template to a string or stream given some context of
>variable names? I'm looking at this from a very different perspective,
>namely *using* various templating engines from an app that otherwise
>doesn't use a framework but still needs templating.

The API I proposed assumes that the template engine gives you WSGI 
application objects, and that you simply pipe them through to your WSGI 
stack.  That is, in the simplest case:

     def some_wsgi_app(environ, start_response):
         template = some_engine.compile_stream(open("mytemplate.foo"))
         environ['wsgi.params'] = {'some_var':'bar'}
         return template(environ, start_response)

The assumption here is that a "template" is just a WSGI application object, 
that maybe has a few extra keys added to the environ, like a params dict 
and/or a "published object".

 From current discussion, however, it seems like the above API will be 
deferred a while to focus on a higher-level API in which you simply ask for 
a template by an opaque ID, e.g.:

     def some_wsgi_app(environ, start_response):
         template = some_engine.find_template("mytemplate")
         environ['wsgi.params'] = {'some_var':'bar'}
         return template(environ, start_response)

So, it's the same except an even simpler, higher-level API.  The API I 
proposed is more useful in the context of a template manager (such as Zope 
3 skins/layers) that might need to support pluggable template 
compilers.  In such circumstances, the compile/write APIs I proposed would 
be useful, but a different API layer than the "get me a template to run" API.

Anyway, part of the reasoning for using WSGI itself as a template API is 
that it allows for template languages that may need to manipulate response 
headers and status, such as the ones that embed Python in HTML or HTML in 
Python.  Or more typically, templates being used to generate non-HTML text, 
such as XML, tab-delimited files, or other kinds of downloads.  It also 
makes it possible for the template language to offer its own native API for 
getting request data.  For example, a ZPT template engine would be free to 
rewrap the WSGI data to appear as standard Zope request/response objects 
from the template's point of view.


>(PS having tried WSGI a bit now I'm fine with it.

WSGI - it's no worse than a trip to East Berlin.  :)


>  Perhaps wsgiref
>should go into the Python 2.5 standard library?)

Sure.  I'd suggest that we might want to expand it a little to include some 
of the fine contributions of other authors, such as Ian's "lint" middleware 
(which sits between an app and a server and checks both for compliance) and 
maybe even his "Python debugger in the browser" middleware.  There have 
also been people who've written a few utilities for CGI-in-WSGI, WSGI in 
mod_python, etc.  And it'd be nice to squeeze in a FastCGI implementation 
if somebody's got a suitable one.  Docs are also nonexistent at the 
moment.  I'd be happy to co-ordinate and consolidate the additions, and of 
course I'll write documentation, though any assistance people can offer 
would be greatly appreciated.  Some people have written nice WSGI tutorials 
or explanations, so if anybody wants to offer those up for consolidation 
into docs, that would be good too.