Developer Interface

This part of the documentation covers staticjinja’s API.

Main Interface

All of staticjinja’s functionality can be accessed by this function, which returns an instance of the Site object.

staticjinja.make_site(searchpath='templates', outpath='.', contexts=None, rules=None, encoding='utf8', extensions=None, staticpaths=None, filters=None, env_globals=None, env_kwargs=None, mergecontexts=False)

Create a Site object.

Parameters:
  • searchpath

    A string representing the absolute path to the directory that the Site should search to discover templates. Defaults to 'templates'.

    If a relative path is provided, it will be coerced to an absolute path by prepending the directory name of the calling module. For example, if you invoke staticjinja using python build.py in directory /foo, then searchpath will be /foo/templates.

  • outpath – A string representing the name of the directory that the Site should store rendered files in. Defaults to '.'.
  • contexts – A list of (regex, context) pairs. The Site will render templates whose name match regex using context. context must be either a dictionary-like object or a function that takes either no arguments or a single jinja2.Template as an argument and returns a dictionary representing the context. Defaults to [].
  • rules – A list of (regex, function) pairs. The Site will delegate rendering to function if regex matches the name of a template during rendering. function must take a jinja2.Environment object, a filename, and a context as parameters and render the template. Defaults to [].
  • encoding – A string representing the encoding that the Site should use when rendering templates. Defaults to 'utf8'.
  • extensions – A list of Jinja extensions that the jinja2.Environment should use. Defaults to [].
  • staticpaths – List of directories to get static files from (relative to searchpath). Defaults to None.
  • filters – A dictionary of Jinja2 filters to add to the Environment. Defaults to {}.
  • env_globals – A mapping from variable names that should be available all the time to their values. Defaults to {}.
  • env_kwargs – A dictionary that will be passed as keyword arguments to the jinja2 Environment. Defaults to {}.
  • mergecontexts – A boolean value. If set to True, then all matching regex from the contexts list will be merged (in order) to get the final context. Otherwise, only the first matching regex is used. Defaults to False.

Classes

class staticjinja.Site(environment, searchpath, outpath, encoding, logger, contexts=None, rules=None, staticpaths=None, mergecontexts=False)

The Site object.

Parameters:
  • environment – A jinja2.Environment.
  • searchpath – A string representing the name of the directory to search for templates.
  • contexts – A list of regex, context pairs. Each context is either a dictionary or a function that takes either no argument or or the current template as its sole argument and returns a dictionary. The regex, if matched against a filename, will cause the context to be used.
  • rules – A list of regex, function pairs used to override template compilation. regex must be a regex which if matched against a filename will cause function to be used instead of the default. function must be a function which takes a Jinja2 Environment, the filename, and the context and renders a template.
  • encoding – The encoding of templates to use.
  • logger – A logging.Logger object used to log events.
  • staticpaths – List of directory names to get static files from (relative to searchpath).
  • mergecontexts – A boolean value. If set to True, then all matching regex from the contexts list will be merged (in order) to get the final context. Otherwise, only the first matching regex is used. Defaults to False.
get_context(template)

Get the context for a template.

If no matching value is found, an empty context is returned. Otherwise, this returns either the matching value if the value is dictionary-like or the dictionary returned by calling it with template if the value is a function.

If several matching values are found, the resulting dictionaries will be merged before being returned if mergecontexts is True. Otherwise, only the first matching value is returned.

Parameters:template – the template to get the context for
get_dependencies(filename)

Get a list of files that depends on the file named filename.

Parameters:filename – the name of the file to find dependencies of
get_rule(template_name)

Find a matching compilation rule for a function.

Raises a ValueError if no matching rule can be found.

Parameters:template_name – the name of the template
get_template(template_name)

Get a jinja2.Template from the environment.

Parameters:template_name – A string representing the name of the template.
is_ignored(filename)

Check if a file is an ignored file.

Ignored files are neither rendered nor used in rendering templates.

A file is considered ignored if it or any of its parent directories are prefixed with an '.'.

Parameters:filename – the name of the file to check
is_partial(filename)

Check if a file is a partial.

Partial files are not rendered, but they are used in rendering templates.

A file is considered a partial if it or any of its parent directories are prefixed with an '_'.

Parameters:filename – the name of the file to check
is_static(filename)

Check if a file is a static file (which should be copied, rather than compiled using Jinja2).

A file is considered static if it lives in any of the directories specified in staticpaths.

Parameters:filename – the name of the file to check
is_template(filename)

Check if a file is a template.

A file is a considered a template if it is neither a partial nor ignored.

Parameters:filename – the name of the file to check
render(use_reloader=False)

Generate the site.

Parameters:use_reloader – if given, reload templates on modification
render_template(template, context=None, filepath=None)

Render a single jinja2.Template object.

If a Rule matching the template is found, the rendering task is delegated to the rule.

Parameters:
  • template – A jinja2.Template to render.
  • context – Optional. A dictionary representing the context to render template with. If no context is provided, get_context() is used to provide a context.
  • filepath – Optional. A file or file-like object to dump the complete template stream into. Defaults to to os.path.join(self.outpath, template.name).
render_templates(templates, filepath=None)

Render a collection of jinja2.Template objects.

Parameters:
  • templates – A collection of Templates to render.
  • filepath – Optional. A file or file-like object to dump the complete template stream into. Defaults to to os.path.join(self.outpath, template.name).
templates

Generator for templates.

class staticjinja.Reloader(site)

Watches site.searchpath for changes and re-renders any changed Templates.

Parameters:site – A Site object.
event_handler(event_type, src_path)

Re-render templates if they are modified.

Parameters:
  • event_type – a string, representing the type of event
  • src_path – the path to the file that triggered the event.
should_handle(event_type, filename)

Check if an event should be handled.

An event should be handled if a file in the searchpath was modified.

Parameters:
  • event_type – a string, representing the type of event
  • filename – the path to the file that triggered the event.
watch()

Watch and reload modified templates.