Developer Interface

This part of the documentation covers staticjinja’s API.

Most of staticjinja’s functionality can be accessed with Site.make_site(), so pay particular attention to that.

Classes

class staticjinja.Site(environment: Environment, searchpath: FilePath, outpath: FilePath = '.', encoding: str = 'utf8', contexts: ContextMapping | None = None, rules: RuleMapping | None = None, staticpaths: list[str] | None = None, mergecontexts: bool = 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. The Site will delegate rendering to function if regex matches the name of a template during rendering. function must take a staticjinja.Site object, a jinja2.Template, and a context dictionary as parameters and render the template. Defaults to [].
  • encoding – The encoding of templates to use.
  • staticpaths –

    Deprecated since version 0.3.4.

    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: Template) → Context

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_dependents(filename: FilePath) → t.Sequence[FilePath]

Get a list of files that depends on filename. Useful to decide what to re-render when filename changes.

  • Ignored files have no dependents.
  • Static and template files just have themselves as dependents.
  • Partial files have all the templates as dependents, since any template may rely upon a partial.

Changed in version 2.0.0: Now always returns list of filenames. Before the return type was either a list of templates or list of filenames.

Parameters:filename – the name of the file to find dependents of
Returns:list of filenames of dependents.
get_rule(template_name: str) → Rule

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: FilePath) → Template

Get a jinja2.Template from the environment.

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

Check if a file is an ignored. 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 – A PathLike name of the file to check
is_partial(filename: FilePath) → bool

Check if a file is 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 – A PathLike name of the file to check
is_static(filename: FilePath) → bool

Check if a file is static. Static files are copied, rather than compiled using Jinja2.

Deprecated since version 0.3.4.

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

Parameters:filename – A PathLike name of the file to check.
is_template(filename: FilePath) → bool

Check if a file is a template.

A file is a considered a template if it is not partial, ignored, or static.

Parameters:filename – A PathLike name of the file to check
classmethod make_site(searchpath: FilePath = 'templates', outpath: FilePath = '.', contexts: ContextMapping | None = None, rules: RuleMapping | None = None, encoding: str = 'utf8', followlinks: bool = True, extensions: list[str] | None = None, staticpaths: list[str] | None = None, filters: dict[str, t.Any] = {}, env_globals: dict[str, t.Any] = {}, env_kwargs: dict[str, t.Any] | None = None, mergecontexts: bool = False) → TSite

Create a Site object.

Parameters:
  • searchpath –

    A string or Path representing the 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 using os.getcwd().

  • 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 staticjinja.Site object, a jinja2.Template, and a context dictionary 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'.
  • followlinks – A boolean describing whether symlinks in searchpath should be followed or not. Defaults to True.
  • extensions – A list of Jinja extensions that the jinja2.Environment should use. Defaults to [].
  • staticpaths –

    Deprecated since version 0.3.4.

    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.
render(use_reloader: bool = False) → None

Generate the site.

Parameters:use_reloader – if given, reload templates on modification
render_template(template: Template, context: Context | None = None, filepath: str | None = None) → 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 PathLike representing the output location. Defaults to to os.path.join(self.outpath, template.name).
render_templates(templates: Iterable[jinja2.environment.Template]) → None

Render a collection of jinja2.Template objects.

Parameters:templates – A collection of jinja2.Template objects to render.
templates

Generator for templates.

class staticjinja.Reloader(site: Site)

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

Parameters:site – A Site object.
event_handler(event_type: str, src_path: FilePath) → None

Re-render templates if they are modified.

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

Check if an event should be handled.

An event should be handled if a file was created or modified, and still exists.

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

Watch and reload modified templates.