A Jinja template loader which allows for:

  • dotted-notation package loading
  • search-path-based overriding of same

Dotted notation

  • Allow a Tool implementer to use a dotted-notation module name (as occuring in the PYTHONPATH), then the given path within the module:




Overriding dotted notation

Allow a Tool implementer to override the theme baseline (or any other Tool’s) templates. This can be lighter-weight than subclassing allura.plugin.ThemeProvider, plus will allow for more fine-grained changes.

This will also override extends and import Jinja tags.

This approach uses a:

  • entry point to a class with...
  • magic files and...
  • (optionally) a class property to specify ordering

File Structure for Overriding dotted notation

For the examples, assume the following directory structure:

|-                     <- entry point specified here
|- newtool/
   |-                    <- entry point target here
   |- templates/
   |  |- index.html             <- Tool's regular templates
   |- override                  <- override_root
      |- allura/                <- magic directory named after module
         |- templates/
            |- repo/
               |- file.html     <- actual template

To override the above example, a Tool implementer would add the following line to their Tool’s (assuming usage in Allura, with the default app_cfg):

newtool =

Then, in the neighbor path (see below) for the file containing the Tool class, add the following path/file:


The template will be overridden. Note that after changing, it would be required to re-initialize with setuptools:

python develop

Specifying search path order with template_path_rules

If a highly specific ordering is required, such as if multiple Tools are trying to override the same template, the entry point target class can also contain a class property template_path_rules:

class NewToolApp(Application):
    template_path_rules = [
        ['>', 'old-tool'],

Each rule specifies a postioner and an entry point or “signpost”. If no rule is provided, the default is ['>', 'allura'].

The “signposts” are:

  • Any other app’s override entry point name
  • site-theme
  • allura (you probably shouldn’t do this)
  • project-theme NOT IMPLEMENTED
  • tool-theme NOT IMPLEMENTED

The positioners are:

This overrider will be found BEFORE the specified entry point
This overrider will be found AFTER the specified entry point
This will replace one of the “signpost” entry points (if multiple apps try to do this for the same signpost, the result is undefined)

TODO: Support multiple partial themes

class allura.lib.package_path_loader.PackagePathLoader(override_entrypoint='allura.theme.override', default_paths=None, override_root='override')
get_source(environment, template)

Returns the source for jinja2 rendered templates. Can understand... - path/to/template.html - module:path/to/template.html


Set up the setuptools entry point-based paths.