genshi.template.loader

Template loading and caching.

TemplateNotFound

Exception raised when a specific template file could not be found.

TemplateLoader

Responsible for loading templates from files on the specified search path.

>>> import tempfile
>>> fd, path = tempfile.mkstemp(suffix='.html', prefix='template')
>>> os.write(fd, '<p>$var</p>')
11
>>> os.close(fd)

The template loader accepts a list of directory paths that are then used when searching for template files, in the given order:

>>> loader = TemplateLoader([os.path.dirname(path)])

The load() method first checks the template cache whether the requested template has already been loaded. If not, it attempts to locate the template file, and returns the corresponding Template object:

>>> from genshi.template import MarkupTemplate
>>> template = loader.load(os.path.basename(path))
>>> isinstance(template, MarkupTemplate)
True

Template instances are cached: requesting a template with the same name results in the same instance being returned:

>>> loader.load(os.path.basename(path)) is template
True

The auto_reload option can be used to control whether a template should be automatically reloaded when the file it was loaded from has been changed. Disable this automatic reloading to improve performance.

>>> os.remove(path)

load(self, filename, relative_to=None, cls=None, encoding=None)

Load the template with the given name.

If the filename parameter is relative, this method searches the search path trying to locate a template matching the given name. If the file name is an absolute path, the search path is ignored.

If the requested template is not found, a TemplateNotFound exception is raised. Otherwise, a Template object is returned that represents the parsed template.

Template instances are cached to avoid having to parse the same template file more than once. Thus, subsequent calls of this method with the same template file name will return the same Template object (unless the auto_reload option is enabled and the file was changed since the last parse.)

If the relative_to parameter is provided, the filename is interpreted as being relative to that path.

param filename:	the relative path of the template file to load
param relative_to:
	the filename of the template from which the new template is being loaded, or None if the template is being loaded directly
param cls:	the class of the template object to instantiate
param encoding:	the encoding of the template to load; defaults to the default_encoding of the loader instance
return:	the loaded Template instance
raises TemplateNotFound:
	if a template with the given name could not be found

directory(path)

Loader factory for loading templates from a local directory.

param path:	the path to the local directory containing the templates
return:	the loader function to load templates from the given directory
rtype:	function

package(name, path)

Loader factory for loading templates from egg package data.

param name:	the name of the package containing the resources
param path:	the path inside the package data
return:	the loader function to load templates from the given package
rtype:	function

prefixed(**delegates)

Factory for a load function that delegates to other loaders depending on the prefix of the requested template path.

The prefix is stripped from the filename when passing on the load request to the delegate.

>>> load = prefixed(
...     app1 = lambda filename: ('app1', filename, None, None),
...     app2 = lambda filename: ('app2', filename, None, None)
... )
>>> print(load('app1/foo.html'))
('app1', 'app1/foo.html', None, None)
>>> print(load('app2/bar.html'))
('app2', 'app2/bar.html', None, None)

param delegates:
	mapping of path prefixes to loader functions
return:	the loader function
rtype:	function

---

See Loading Templates, ApiDocs/0.6.x, Documentation