[Web-SIG] My original template API proposal

[Phillip J. Eby]

At 02:46 PM 2/5/2006 -0600, Ian Bicking wrote:
>Ian Bicking wrote:
> >       def render(template_instance, vars, format="html", fragment=False):
>
>Here I can magically turn this into a WEB templating spec:
>
>def render(template_instance, vars, format="html", fragment=False,
>wsgi_environ=None, set_header_callback=None)
>
>wsgi_environ is the environ dictionary if this is being called in a WSGI
>context.  set_header_callback can be called like
>set_header_callback(header_name, header_value) to write such a header to
>the response.  Frameworks may or may not allow for setting headers.  If
>they don't allow for it, they shouldn't provide that callback (thus
>headers will not be mysteriously thrown away -- instead they will be
>rejected immediately).  [Should set_header_callback('Status', '404 Not
>Found') be used, or a separate callback, or...?]
>
>This follows what all "server pages" templates I know of do.  That is,
>they do not have special syntax related to any metadata (i.e., headers)
>or even any special syntax related to web requests.  Instead the web
>request is represented through some set of variables available in the
>template.

Yes, but different template systems offer different APIs based on it; the 
idea of using WSGI here was to make it possible for them to offer their 
*own*, native APIs under this spec, not to force the use of the host 
framework's API.

The only thing that's missing from your proposal is streaming control or 
large file support.  I'll agree that it's an edge use case, but it seems to 
me just as easy to just offer a plain WSGI interface and not have to 
document a bunch of differences and limitations.  OTOH, if this is what it 
takes to get consensus, so be it.

The additional advantage to using plain ol' WSGI as the calling interface, 
however, is that it also lets you embed *anything* as a template, including 
whole applications if they provide a "template engine" whose syntax is 
actually the application's configuration.

Anyway, the only differences I'm aware of between what you're proposing and 
what I'm proposing are:

1. Syntax sugar (each proposal sweetens different use cases)
2. Feature restrictions (yours takes away streaming)
3. What's optional (you consider WSGI optional, I want strings to be optional)

It would be better, I think, to address further discussion to addressing 
the actual points of difference.

Regarding #2, I'm willing to compromise to get consensus.  Regarding #3, 
I'd be willing to compromise by making *both* optional, with clearly 
defined variations of the spec so that plugins and frameworks that support 
each are clearly distinguishable.  This would also mean that we'd both be 
able to get the syntaxes we want under #1.