[Web-SIG] My original template API proposal

[Ian Bicking]

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)

I've updated this spec 
(http://svn.pythonpaste.org/home/ianb/templateapi/interface.py) with a 
new version of the render method:


      def render(template_instance, vars, wsgi_environ=None,
                 set_header_callback=None, **kwargs):
          """
          Render the template instance (as returned by
          ``load_resource``).  [Should there be some way to return
          metadata about what was rendered, like the type of object
          being returned -- e.g., text/html or text/plain?]

          ``vars`` is typically a dictionary (-like object) of
          variables for use in substitution.

          ``wsgi_environ``, if given, is the WSGI environment
          dictionary.  Templates are free to create their own native
          wrappers of this environment.  [Is there anything specifying
          where *here* is?  Is SCRIPT_NAME authoritative in this case?
          Any standard for the application root?  Maybe a special key,
          e.g., wsgi.application_root]

          ``set_header_callback`` is a function that can be called like
          ``set_header_callback(header_name, header_value)``.
          Arguments can only be strings (not unicode) [encode unicode
          with ASCII?].  The header named ``'Status'`` can be used to
          set the status.  Even if this template is rendered in a web
          environment, frameworks may not provide this callback if they
          do not expect or wish the template to effect the headers.

          Other keyword arguments can be provided, with meaning
          specific to the templating language.  Plugins should ignore
          keyword arguments they do not understand. [Is this a good
          idea?]

          This function returns an iterator which produces strings or
          unicode strings.  (It should produce one or the other, not
          both.)  Unicode is preferred.

          If you want a template to render to something else -- for
          example, ElementTree objects -- you should provide another
          method with the same signature as this.  Consumers can fall
          back to getting the string with this method, like::

              template = plugin.load_template(...)
              try:
                  meth = plugin.render_elementtree
              except AttributeError:
                  result = ''.join(plugin.render(template, ...))
                  result = ElementTree.XML(result)
              else:
                  result = meth(template, ...)
          """





-- 
Ian Bicking  |  ianb at colorstudy.com  |  http://blog.ianbicking.org